@12-apps/ui 1.0.0 → 1.3.0

package/src/components/layout/ScrollArea/ScrollViewport.tsx

@@ -0,0 +1,90 @@
+import { Box, useTheme } from '@mui/material';
+import type { FC, ReactNode, UIEvent } from 'react';
+import React from 'react';
+
+import { getOverflowStyle, getVariantStyles } from './ScrollArea.styles';
+import type { ResolvedScrollAreaProps } from './ScrollArea.helpers';
+
+export interface ScrollViewportProps
+  extends Pick<
+    ResolvedScrollAreaProps,
+    | 'height'
+    | 'maxHeight'
+    | 'orientation'
+    | 'scrollbarSize'
+    | 'scrollbarColor'
+    | 'scrollbarTrackColor'
+    | 'contentPadding'
+    | 'variant'
+    | 'disabled'
+    | 'loading'
+    | 'smoothScroll'
+  > {
+  children: ReactNode;
+  shouldShowScrollbar: boolean;
+  setScrollRef: (node: HTMLDivElement | null) => void;
+  onScroll: (event: UIEvent<HTMLDivElement>) => void;
+}
+
+// The element that actually scrolls: its own overflow and scrollbar styling,
+// plus the disabled and loading treatments.
+export const ScrollViewport: FC<ScrollViewportProps> = ({
+  children,
+  height,
+  maxHeight,
+  orientation,
+  scrollbarSize,
+  scrollbarColor,
+  scrollbarTrackColor,
+  contentPadding,
+  variant,
+  disabled,
+  loading,
+  smoothScroll,
+  shouldShowScrollbar,
+  setScrollRef,
+  onScroll,
+}) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      ref={setScrollRef}
+      onScroll={onScroll}
+      role="region"
+      aria-label="Scrollable content"
+      aria-busy={loading}
+      tabIndex={disabled ? -1 : 0}
+      sx={{
+        width: '100%',
+        height: '100%',
+        // Use an explicit maxHeight when height is 'auto', else inherit.
+        maxHeight: height === 'auto' && maxHeight ? maxHeight : '100%',
+        padding: contentPadding,
+        opacity: loading ? 0.5 : 1,
+        pointerEvents: disabled || loading ? 'none' : 'auto',
+        transition: 'opacity 0.3s ease',
+        '&:focus': {
+          outline: 'none',
+          '&:focus-visible': {
+            outline: `2px solid ${theme.palette.primary.main}`,
+            outlineOffset: -2,
+          },
+        },
+        ...getOverflowStyle({ disabled, orientation }),
+        ...getVariantStyles({
+          theme,
+          variant,
+          orientation,
+          scrollbarSize,
+          scrollbarColor,
+          scrollbarTrackColor,
+          shouldShowScrollbar,
+        }),
+      }}
+      style={{ scrollBehavior: smoothScroll ? 'smooth' : 'auto' }}
+    >
+      {children}
+    </Box>
+  );
+};

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

@@ -0,0 +1,128 @@
+import type { CSSObject, Theme } from '@mui/material';
+
+import type {
+  SeparatorOrientation,
+  SeparatorProps,
+  SeparatorSize,
+  SeparatorVariant,
+} from './Separator.types';
+
+const THICKNESS_PX: Record<SeparatorSize, number> = {
+  xs: 1,
+  sm: 2,
+  md: 3,
+  lg: 4,
+  xl: 6,
+};
+
+const MARGIN_PX: Record<SeparatorSize, number> = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+};
+
+const separatorThickness = (size: SeparatorSize): number =>
+  THICKNESS_PX[size] ?? THICKNESS_PX.md;
+
+/** An explicit `margin` wins; otherwise the size picks one. */
+export const separatorMargin = (
+  size: SeparatorSize,
+  margin?: number | string,
+): number | string => margin ?? MARGIN_PX[size] ?? MARGIN_PX.md;
+
+// `gradient` paints a background rather than a border, so it draws its line as a
+// solid border of zero visual consequence.
+const borderStyleFor = (variant: SeparatorVariant): 'dashed' | 'dotted' | 'solid' => {
+  switch (variant) {
+    case 'dashed':
+      return 'dashed';
+    case 'dotted':
+      return 'dotted';
+    default:
+      return 'solid';
+  }
+};
+
+const gradientBackground = (
+  variant: SeparatorVariant,
+  orientation: SeparatorOrientation,
+  color: string,
+): string | undefined => {
+  if (variant !== 'gradient') return undefined;
+  const angle = orientation === 'horizontal' ? '90deg' : '180deg';
+  return `linear-gradient(${angle}, transparent 0%, ${color} 50%, transparent 100%)`;
+};
+
+// Only the leading edge carries the rule; the other three are zeroed explicitly so
+// a parent's border shorthand cannot leak through.
+const borderEdges = (
+  isHorizontal: boolean,
+  thickness: number,
+  style: 'dashed' | 'dotted' | 'solid',
+  color: string,
+): CSSObject => {
+  const leading = isHorizontal ? 'Top' : 'Left';
+  const blank: CSSObject = {
+    borderTopWidth: 0,
+    borderBottomWidth: 0,
+    borderLeftWidth: 0,
+    borderRightWidth: 0,
+    borderTopStyle: 'none',
+    borderBottomStyle: 'none',
+    borderLeftStyle: 'none',
+    borderRightStyle: 'none',
+    borderTopColor: 'transparent',
+    borderBottomColor: 'transparent',
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent',
+  };
+
+  return {
+    ...blank,
+    [`border${leading}Width`]: thickness,
+    [`border${leading}Style`]: style,
+    [`border${leading}Color`]: color,
+  };
+};
+
+type SeparatorStyleArgs = Required<
+  Pick<SeparatorProps, 'variant' | 'orientation' | 'size'>
+> &
+  Pick<SeparatorProps, 'color' | 'margin' | 'length'>;
+
+export const separatorStyles = (
+  theme: Theme,
+  { variant, orientation, size, color, margin, length }: SeparatorStyleArgs,
+): CSSObject => {
+  const isHorizontal = orientation === 'horizontal';
+  const thickness = separatorThickness(size);
+  const resolvedColor = color || theme.palette.divider;
+
+  // A margin given as a string carries its own units; a number is pixels.
+  const marginValue = separatorMargin(size, margin);
+  const marginStr = typeof marginValue === 'string' ? marginValue : `${marginValue}px`;
+
+  const baseStyles: CSSObject = {
+    display: 'flex',
+    alignItems: 'center',
+    margin: isHorizontal ? `${marginStr} 0` : `0 ${marginStr}`,
+    width: isHorizontal ? length || '100%' : `${thickness}px`,
+    height: isHorizontal ? `${thickness}px` : length || '100%',
+    boxSizing: 'border-box',
+  };
+
+  if (variant === 'gradient') {
+    return {
+      ...baseStyles,
+      background: gradientBackground(variant, orientation, resolvedColor),
+    };
+  }
+
+  return {
+    ...baseStyles,
+    backgroundColor: 'transparent',
+    ...borderEdges(isHorizontal, thickness, borderStyleFor(variant), resolvedColor),
+  };
+};

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

@@ -486,22 +486,13 @@ export const Performance: Story = {
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
 
-    await step('Measure render time for multiple separators', async () => {
-
-      const startTime = performance.now();
+    // This bracketed the query below with performance.now() and asserted a
+    // wall-clock budget. That measured the machine, not the component.
+    await step('Render multiple separators', async () => {
       const separators = canvas.getAllByRole('separator');
 
-      const endTime = performance.now();
-
-      const renderTime = endTime - startTime;
-      // eslint-disable-next-line no-console
-      console.log(`Render time for ${separators.length} separators: ${renderTime}ms`);
-
       // Verify all separators are rendered
       await expect(separators.length).toBe(20);
-
-      // Assert reasonable render time (adjust threshold as needed)
-      await expect(renderTime).toBeLessThan(100);
     });
 
     await step('Test memory usage with many separators', async () => {

package/src/components/layout/Separator/Separator.tsx

@@ -1,6 +1,7 @@
 import { Box, Typography,useTheme } from '@mui/material';
 import React from 'react';
 
+import { separatorMargin, separatorStyles } from './Separator.styles';
 import type { SeparatorProps } from './Separator.types';
 
 export const Separator: React.FC<SeparatorProps> = ({
@@ -15,134 +16,7 @@ export const Separator: React.FC<SeparatorProps> = ({
   'data-testid': dataTestId,
 }) => {
   const theme = useTheme();
-
-  const getThickness = () => {
-    switch (size) {
-      case 'xs':
-        return 1;
-      case 'sm':
-        return 2;
-      case 'md':
-        return 3;
-      case 'lg':
-        return 4;
-      case 'xl':
-        return 6;
-      default:
-        return 3;
-    }
-  };
-
-  const getMargin = () => {
-    if (margin !== undefined) return margin;
-    switch (size) {
-      case 'xs':
-        return 4; // 0.5 * 8 = 4px
-      case 'sm':
-        return 8; // 1 * 8 = 8px
-      case 'md':
-        return 16; // 2 * 8 = 16px
-      case 'lg':
-        return 24; // 3 * 8 = 24px
-      case 'xl':
-        return 32; // 4 * 8 = 32px
-      default:
-        return 16;
-    }
-  };
-
-  const getBorderStyle = () => {
-    switch (variant) {
-      case 'dashed':
-        return 'dashed';
-      case 'dotted':
-        return 'dotted';
-      case 'gradient':
-        return 'solid';
-      default:
-        return 'solid';
-    }
-  };
-
-  const getColor = () => {
-    if (color) return color;
-    return theme.palette.divider;
-  };
-
-  const getGradientBackground = () => {
-    if (variant !== 'gradient') return undefined;
-
-    if (orientation === 'horizontal') {
-      return `linear-gradient(90deg, transparent 0%, ${getColor()} 50%, transparent 100%)`;
-    } else {
-      return `linear-gradient(180deg, transparent 0%, ${getColor()} 50%, transparent 100%)`;
-    }
-  };
-
-  const getSeparatorStyles = () => {
-    const isHorizontal = orientation === 'horizontal';
-    const thickness = getThickness();
-    const marginValue = getMargin();
-
-    // Handle margin - if it's a string with units, use as-is, otherwise add px
-    const marginStr = typeof marginValue === 'string' ? marginValue : `${marginValue}px`;
-
-    const baseStyles = {
-      display: 'flex' as const,
-      alignItems: 'center' as const,
-      margin: isHorizontal ? `${marginStr} 0` : `0 ${marginStr}`,
-      width: isHorizontal ? length || '100%' : `${thickness}px`,
-      height: isHorizontal ? `${thickness}px` : length || '100%',
-      boxSizing: 'border-box' as const,
-    };
-
-    if (variant === 'gradient') {
-      return {
-        ...baseStyles,
-        background: getGradientBackground(),
-      };
-    }
-
-    // Apply border styles separately for better compatibility with MUI's sx prop
-    const borderStyle = getBorderStyle();
-    const borderColor = getColor();
-
-    const borderStyles = isHorizontal
-      ? {
-          borderTopWidth: thickness,
-          borderTopStyle: borderStyle,
-          borderTopColor: borderColor,
-          borderBottomWidth: 0,
-          borderLeftWidth: 0,
-          borderRightWidth: 0,
-          borderBottomStyle: 'none',
-          borderLeftStyle: 'none',
-          borderRightStyle: 'none',
-          borderBottomColor: 'transparent',
-          borderLeftColor: 'transparent',
-          borderRightColor: 'transparent',
-        }
-      : {
-          borderLeftWidth: thickness,
-          borderLeftStyle: borderStyle,
-          borderLeftColor: borderColor,
-          borderTopWidth: 0,
-          borderBottomWidth: 0,
-          borderRightWidth: 0,
-          borderTopStyle: 'none',
-          borderBottomStyle: 'none',
-          borderRightStyle: 'none',
-          borderTopColor: 'transparent',
-          borderBottomColor: 'transparent',
-          borderRightColor: 'transparent',
-        };
-
-    return {
-      ...baseStyles,
-      backgroundColor: 'transparent' as const,
-      ...borderStyles,
-    };
-  };
+  const styles = separatorStyles(theme, { variant, orientation, size, color, margin, length });
 
   if (children) {
     const isHorizontal = orientation === 'horizontal';
@@ -153,12 +27,12 @@ export const Separator: React.FC<SeparatorProps> = ({
         sx={{
           display: 'flex',
           alignItems: 'center',
-          margin: getMargin(),
+          margin: separatorMargin(size, margin),
           flexDirection: isHorizontal ? 'row' : 'column',
           gap: theme.spacing(2),
         }}
       >
-        <Box sx={getSeparatorStyles()} />
+        <Box sx={styles} />
         <Typography
           variant="body2"
           color="text.secondary"
@@ -170,7 +44,7 @@ export const Separator: React.FC<SeparatorProps> = ({
         >
           {children}
         </Typography>
-        <Box sx={getSeparatorStyles()} />
+        <Box sx={styles} />
       </Box>
     );
   }
@@ -178,7 +52,7 @@ export const Separator: React.FC<SeparatorProps> = ({
   return (
     <Box
       className={className}
-      sx={getSeparatorStyles()}
+      sx={styles}
       role="separator"
       aria-orientation={orientation}
       data-testid={dataTestId}

package/src/components/layout/SettingsLayout/SettingsLayout.parts.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { ExpandMore as ExpandMoreIcon, Search as SearchIcon } from '@mui/icons-material';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import SearchIcon from '@mui/icons-material/Search';
 import {
   alpha,
   Box,

package/src/components/layout/SettingsLayout/SettingsLayout.stories.tsx

@@ -1,11 +1,9 @@
-import {
-  LanguageOutlined,
-  LockOutlined,
-  NotificationsOutlined,
-  PaletteOutlined,
-  PaymentOutlined,
-  PersonOutlined,
-} from '@mui/icons-material';
+import LanguageOutlined from '@mui/icons-material/LanguageOutlined';
+import LockOutlined from '@mui/icons-material/LockOutlined';
+import NotificationsOutlined from '@mui/icons-material/NotificationsOutlined';
+import PaletteOutlined from '@mui/icons-material/PaletteOutlined';
+import PaymentOutlined from '@mui/icons-material/PaymentOutlined';
+import PersonOutlined from '@mui/icons-material/PersonOutlined';
 import { Box, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';

package/src/components/layout/Sidebar/Sidebar.stories.tsx

@@ -1,15 +1,13 @@
-import {
-  ChevronLeft as ChevronLeftIcon,
-  ChevronRight as ChevronRightIcon,
-  Dashboard as DashboardIcon,
-  Home as HomeIcon,
-  Inbox as InboxIcon,
-  Menu as MenuIcon,
-  Person as PersonIcon,
-  Send as SendIcon,
-  Settings as SettingsIcon,
-  Star as StarIcon,
-} from '@mui/icons-material';
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import HomeIcon from '@mui/icons-material/Home';
+import InboxIcon from '@mui/icons-material/Inbox';
+import MenuIcon from '@mui/icons-material/Menu';
+import PersonIcon from '@mui/icons-material/Person';
+import SendIcon from '@mui/icons-material/Send';
+import SettingsIcon from '@mui/icons-material/Settings';
+import StarIcon from '@mui/icons-material/Star';
 import {
   Avatar,
   Box,

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

@@ -1,15 +1,13 @@
-import {
-  ChevronLeft as ChevronLeftIcon,
-  ChevronRight as ChevronRightIcon,
-  Dashboard as DashboardIcon,
-  Home as HomeIcon,
-  Inbox as InboxIcon,
-  Menu as MenuIcon,
-  Person as PersonIcon,
-  Send as SendIcon,
-  Settings as SettingsIcon,
-  Star as StarIcon,
-} from '@mui/icons-material';
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import HomeIcon from '@mui/icons-material/Home';
+import InboxIcon from '@mui/icons-material/Inbox';
+import MenuIcon from '@mui/icons-material/Menu';
+import PersonIcon from '@mui/icons-material/Person';
+import SendIcon from '@mui/icons-material/Send';
+import SettingsIcon from '@mui/icons-material/Settings';
+import StarIcon from '@mui/icons-material/Star';
 import {
   Avatar,
   Box,
@@ -265,35 +263,35 @@ export const KeyboardNavigation: Story = {
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 
-    // Test Tab navigation through sidebar items
+    // Test Tab navigation through sidebar items. The first nav item is the
+    // first focusable node in the story, so tabbing in from the body reaches it
+    // — the old .focus() call asserted only that focus() works.
     const firstNavItem = canvas.getByTestId('keyboard-nav-home');
-    firstNavItem.focus();
-    await expect(firstNavItem).toHaveFocus();
+    await userEvent.tab();
+    await waitFor(() => expect(firstNavItem).toHaveFocus());
+
+    // Enter key activation, checked here while focus is already on the item
+    // rather than by re-focusing it at the end of the journey.
+    await userEvent.keyboard('{Enter}');
+    await expect(firstNavItem).toBeInTheDocument();
 
     // Tab to next item
     await userEvent.tab();
-    await expect(canvas.getByTestId('keyboard-nav-dashboard')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('keyboard-nav-dashboard')).toHaveFocus());
 
     // Tab to next item
     await userEvent.tab();
-    await expect(canvas.getByTestId('keyboard-nav-inbox')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('keyboard-nav-inbox')).toHaveFocus());
 
     // Tab to footer button
     await userEvent.tab();
     await userEvent.tab();
     await userEvent.tab();
-    await expect(canvas.getByTestId('footer-button')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('footer-button')).toHaveFocus());
 
     // Tab to main content
     await userEvent.tab();
-    await expect(canvas.getByTestId('main-button')).toHaveFocus();
-
-    // Test Enter key activation
-    const homeItem = canvas.getByTestId('keyboard-nav-home');
-    homeItem.focus();
-    await userEvent.keyboard('{Enter}');
-    // Verify item is still accessible after Enter
-    await expect(homeItem).toBeInTheDocument();
+    await waitFor(() => expect(canvas.getByTestId('main-button')).toHaveFocus());
   },
 };
 
@@ -460,22 +458,22 @@ export const FocusManagement: Story = {
 
     // Test initial focus on first sidebar item
     const firstItem = canvas.getByTestId('focus-nav-home');
-    firstItem.focus();
-    await expect(firstItem).toHaveFocus();
+    await userEvent.tab();
+    await waitFor(() => expect(firstItem).toHaveFocus());
 
     // Test focus moves through sidebar elements
     await userEvent.tab();
-    await expect(canvas.getByTestId('focus-nav-dashboard')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('focus-nav-dashboard')).toHaveFocus());
 
     await userEvent.tab();
-    await expect(canvas.getByTestId('focus-nav-inbox')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('focus-nav-inbox')).toHaveFocus());
 
     await userEvent.tab();
-    await expect(canvas.getByTestId('sidebar-action')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('sidebar-action')).toHaveFocus());
 
     // Test focus moves to main content
     await userEvent.tab();
-    await expect(canvas.getByTestId('main-focus-button')).toHaveFocus();
+    await waitFor(() => expect(canvas.getByTestId('main-focus-button')).toHaveFocus());
 
     // Test hiding sidebar
     const hideButton = canvas.getByTestId('hide-sidebar-button');
@@ -791,8 +789,7 @@ export const VisualStates: Story = {
     await expect(canvas.getByTestId('expanded-footer')).toBeInTheDocument();
 
     // Test sidebar width when expanded
-    let sidebarStyles = window.getComputedStyle(sidebar);
-    await expect(sidebarStyles.width).toBe('280px');
+    await expect(window.getComputedStyle(sidebar).width).toBe('280px');
 
     // Test collapsing
     const collapseToggle = canvas.getByTestId('collapse-toggle');
@@ -802,10 +799,11 @@ export const VisualStates: Story = {
       expect(canvas.getByTestId('collapse-status')).toHaveTextContent('Sidebar is collapsed');
     });
 
-    // Test sidebar width when collapsed
+    // Test sidebar width when collapsed. Read the computed style inside the
+    // waitFor rather than reassigning an outer variable from it — the callback
+    // reruns, so the shared binding held whichever value the last retry left.
     await waitFor(() => {
-      sidebarStyles = window.getComputedStyle(sidebar);
-      expect(sidebarStyles.width).toBe('64px');
+      expect(window.getComputedStyle(sidebar).width).toBe('64px');
     });
 
     // Test collapsed avatar is visible

package/src/components/layout/Skeleton/Skeleton.helpers.ts

@@ -0,0 +1,33 @@
+import type { SkeletonProps } from './Skeleton.types';
+
+type SkeletonDefaultedKeys =
+  | 'variant'
+  | 'animation'
+  | 'count'
+  | 'spacing'
+  | 'intensity'
+  | 'glassmorphism'
+  | 'shimmer';
+
+type ResolvedSkeletonProps = SkeletonProps &
+  Required<Pick<SkeletonProps, SkeletonDefaultedKeys>>;
+
+const SKELETON_DEFAULTS: Pick<SkeletonProps, SkeletonDefaultedKeys> = {
+  variant: 'text',
+  animation: 'pulse',
+  count: 1,
+  spacing: 1,
+  intensity: 'medium',
+  glassmorphism: false,
+  shimmer: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `count={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: SkeletonProps): Partial<SkeletonProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<SkeletonProps>;
+
+export const resolveSkeletonProps = (props: SkeletonProps): ResolvedSkeletonProps =>
+  ({ ...SKELETON_DEFAULTS, ...definedProps(props) }) as ResolvedSkeletonProps;