@12-apps/ui 1.0.0 → 1.3.1

package/src/components/navigation/Tabs/TabsPanel.tsx

@@ -0,0 +1,100 @@
+import { Box, CircularProgress, Fade } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import type { TabPanelProps } from './Tabs.types';
+
+const TabPanel = styled(Box, {
+  shouldForwardProp: (prop) => !['animate', 'persist'].includes(prop as string),
+})<{ animate?: boolean; persist?: boolean }>(({ animate, persist }) => ({
+  width: '100%',
+
+  ...(animate && {
+    transition: 'all 0.3s ease-in-out',
+  }),
+
+  ...(persist && {
+    '&[hidden]': {
+      display: 'none !important',
+    },
+  }),
+}));
+
+const LoadingContainer = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minHeight: 200,
+  color: theme.palette.text.secondary,
+}));
+
+// A loading panel shows the caller's placeholder, or a spinner if there isn't one.
+const panelContent = (
+  loading: boolean,
+  loadingComponent: React.ReactNode,
+  children: React.ReactNode,
+): React.ReactNode => {
+  if (!loading) return children;
+
+  return (
+    loadingComponent || (
+      <LoadingContainer>
+        <CircularProgress size={32} />
+      </LoadingContainer>
+    )
+  );
+};
+
+const panelTestId = (dataTestId: string | undefined, index: number): string =>
+  dataTestId ? `${dataTestId}-panel-${index}` : `tabs-panel-${index}`;
+
+export const CustomTabPanel: React.FC<TabPanelProps & { dataTestId?: string; index: number }> = ({
+  children,
+  id,
+  value,
+  animate = false,
+  animationDuration = 300,
+  persist = false,
+  loading = false,
+  loadingComponent,
+  className,
+  dataTestId,
+  index,
+  ...props
+}) => {
+  const isActive = value === id;
+  const shouldRender = isActive || persist;
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  const content = panelContent(loading, loadingComponent, children);
+  const testId = panelTestId(dataTestId, index);
+
+  const panel = (
+    <TabPanel
+      role="tabpanel"
+      hidden={!isActive}
+      id={`tabpanel-${id}`}
+      aria-labelledby={`tab-${id}`}
+      animate={animate}
+      persist={persist}
+      className={className}
+      data-testid={testId}
+      {...props}
+    >
+      {content}
+    </TabPanel>
+  );
+
+  // The animated and plain panels are the same element; only the Fade wrapper
+  // differs.
+  if (!animate) return panel;
+
+  return (
+    <Fade in={isActive} timeout={animationDuration}>
+      {panel}
+    </Fade>
+  );
+};

package/src/components/typography/Blockquote/Blockquote.tsx

@@ -1,4 +1,4 @@
-import { FormatQuote } from '@mui/icons-material';
+import FormatQuote from '@mui/icons-material/FormatQuote';
 import type { Theme} from '@mui/material';
 import { alpha, Box,Typography } from '@mui/material';
 import { styled } from '@mui/material/styles';

package/src/components/typography/Code/Code.test.stories.tsx

@@ -1,7 +1,7 @@
 import { Box, createTheme,ThemeProvider, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
-import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import { Code } from './Code';
 
@@ -189,8 +189,8 @@ export const KeyboardNavigation: Story = {
       const copyButton = canvas.getByRole('button', { name: /copy code/i });
 
       // Focus the copy button
-      copyButton.focus();
-      expect(copyButton).toHaveFocus();
+      await userEvent.click(copyButton);
+      await waitFor(() => expect(copyButton).toHaveFocus());
 
       // Test Enter key
       await userEvent.keyboard('{Enter}');
@@ -213,8 +213,8 @@ export const KeyboardNavigation: Story = {
 
       // Focus the first button (which should be the copy button)
       const copyButton = buttons[0];
-      copyButton.focus();
-      expect(copyButton).toHaveFocus();
+      await userEvent.click(copyButton);
+      await waitFor(() => expect(copyButton).toHaveFocus());
 
       // Verify that keyboard navigation works by checking the button is focusable
       expect(copyButton).toHaveAttribute('tabindex');

package/src/components/typography/Code/Code.tsx

@@ -1,4 +1,5 @@
-import { Check,ContentCopy } from '@mui/icons-material';
+import Check from '@mui/icons-material/Check';
+import ContentCopy from '@mui/icons-material/ContentCopy';
 import { alpha,Box, IconButton, Tooltip } from '@mui/material';
 import { styled } from '@mui/material/styles';
 import React, { useState } from 'react';
@@ -139,6 +140,73 @@ const LanguageLabel = styled(Box)(({ theme }) => ({
   boxShadow: theme.palette.mode === 'light' ? theme.shadows[1] : 'none',
 }));
 
+// Renders each source line beside a gutter number. Keys combine the line number
+// with a slice of the content and its length, so editing one line in place does
+// not reshuffle the keys of the lines around it.
+const renderNumberedLines = (source: string) =>
+  source.split('\n').map((line, index) => {
+    const stableKey = `line-${index + 1}-${line.slice(0, 10).replace(/\s+/g, '')}-${line.length}`;
+
+    return (
+      <div key={stableKey} style={{ display: 'flex' }}>
+        <span
+          style={{
+            display: 'inline-block',
+            minWidth: '3em',
+            opacity: 0.5,
+            userSelect: 'none',
+            marginRight: '1em',
+            textAlign: 'right',
+          }}
+        >
+          {index + 1}
+        </span>
+        <span>{line}</span>
+      </div>
+    );
+  });
+
+// Only block-ish variants get a language label or a copy affordance.
+const resolveCodeFlags = (
+  variant: CodeProps['variant'],
+  copyable: boolean,
+  language: CodeProps['language'],
+) => {
+  const isBlock = variant === 'block' || variant === 'highlight';
+  return {
+    isBlock,
+    showCopy: copyable && isBlock,
+    showLanguage: Boolean(language) && isBlock,
+  };
+};
+
+// Owns its own "just copied" flash. Keeping it here rather than inline in Code
+// means the copied/not-copied branches do not count against the main render, and
+// the flash re-renders only the button. Non-string children are still a no-op on
+// click, exactly as before.
+const CodeCopyButton: React.FC<{ source: React.ReactNode }> = ({ source }) => {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    if (typeof source !== 'string') return;
+    try {
+      await navigator.clipboard.writeText(source);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Silently fail if clipboard access is denied
+    }
+  };
+
+  return (
+    <Tooltip title={copied ? 'Copied!' : 'Copy code'}>
+      <CopyButton onClick={handleCopy} size="small" color={copied ? 'success' : 'default'}>
+        {copied ? <Check /> : <ContentCopy />}
+      </CopyButton>
+    </Tooltip>
+  );
+};
+
 export const Code = React.forwardRef<HTMLElement, CodeProps>(
   (
     {
@@ -152,23 +220,7 @@ export const Code = React.forwardRef<HTMLElement, CodeProps>(
     },
     ref,
   ) => {
-    const [copied, setCopied] = useState(false);
-
-    const handleCopy = async () => {
-      if (typeof children === 'string') {
-        try {
-          await navigator.clipboard.writeText(children);
-          setCopied(true);
-          window.setTimeout(() => setCopied(false), 2000);
-        } catch {
-          // Silently fail if clipboard access is denied
-        }
-      }
-    };
-
-    const isBlock = variant === 'block' || variant === 'highlight';
-    const shouldShowCopy = copyable && isBlock;
-    const shouldShowLanguage = language && isBlock;
+    const { isBlock, showCopy, showLanguage } = resolveCodeFlags(variant, copyable, language);
 
     // Process children for line numbers if needed
     const processedChildren = React.useMemo(() => {
@@ -176,28 +228,7 @@ export const Code = React.forwardRef<HTMLElement, CodeProps>(
         return children;
       }
 
-      return children.split('\n').map((line, index) => {
-        // Use line content hash + line number for more stable keys
-        const stableKey = `line-${index + 1}-${line.slice(0, 10).replace(/\s+/g, '')}-${line.length}`;
-        
-        return (
-          <div key={stableKey} style={{ display: 'flex' }}>
-            <span
-              style={{
-                display: 'inline-block',
-                minWidth: '3em',
-                opacity: 0.5,
-                userSelect: 'none',
-                marginRight: '1em',
-                textAlign: 'right',
-              }}
-            >
-              {index + 1}
-            </span>
-            <span>{line}</span>
-          </div>
-        );
-      });
+      return renderNumberedLines(children);
     }, [children, lineNumbers, isBlock]);
 
     return (
@@ -206,20 +237,14 @@ export const Code = React.forwardRef<HTMLElement, CodeProps>(
         component={variant === 'inline' ? 'span' : 'div'}
         customVariant={variant}
         customSize={size}
-        copyable={shouldShowCopy}
+        copyable={showCopy}
         {...props}
       >
-        {shouldShowLanguage && <LanguageLabel>{language}</LanguageLabel>}
+        {showLanguage && <LanguageLabel>{language}</LanguageLabel>}
 
         <StyledCode>{processedChildren}</StyledCode>
 
-        {shouldShowCopy && (
-          <Tooltip title={copied ? 'Copied!' : 'Copy code'}>
-            <CopyButton onClick={handleCopy} size="small" color={copied ? 'success' : 'default'}>
-              {copied ? <Check /> : <ContentCopy />}
-            </CopyButton>
-          </Tooltip>
-        )}
+        {showCopy && <CodeCopyButton source={children} />}
       </StyledCodeContainer>
     );
   },

package/src/components/typography/Heading/Heading.test.stories.tsx

@@ -89,10 +89,10 @@ const FocusManagementComponent = () => {
     h3: React.useRef<globalThis.HTMLHeadingElement>(null),
   };
 
-  const focusHeading = (level: string) => {
+  const focusHeading = async (level: string) => {
     const ref = headingRefs[level as keyof typeof headingRefs];
     if (ref.current) {
-      ref.current.focus();
+      await userEvent.click(ref.current);
       setActiveHeading(level);
     }
   };
@@ -342,21 +342,21 @@ export const KeyboardNavigation: Story = {
 
     // Tab to first heading
     await userEvent.tab();
-    expect(h1).toHaveFocus();
+    await waitFor(() => expect(h1).toHaveFocus());
     await waitFor(() => {
       expect(focusDisplay).toHaveTextContent('Focused: h1');
     });
 
     // Tab to second heading
     await userEvent.tab();
-    expect(h2).toHaveFocus();
+    await waitFor(() => expect(h2).toHaveFocus());
     await waitFor(() => {
       expect(focusDisplay).toHaveTextContent('Focused: h2');
     });
 
     // Tab to third heading
     await userEvent.tab();
-    expect(h3).toHaveFocus();
+    await waitFor(() => expect(h3).toHaveFocus());
     await waitFor(() => {
       expect(focusDisplay).toHaveTextContent('Focused: h3');
     });
@@ -433,21 +433,21 @@ export const FocusManagement: Story = {
 
     // Focus H1
     await userEvent.click(focusH1Btn);
-    expect(h1).toHaveFocus();
+    await waitFor(() => expect(h1).toHaveFocus());
     await waitFor(() => {
       expect(activeDisplay).toHaveTextContent('Active: h1');
     });
 
     // Focus H2
     await userEvent.click(focusH2Btn);
-    expect(h2).toHaveFocus();
+    await waitFor(() => expect(h2).toHaveFocus());
     await waitFor(() => {
       expect(activeDisplay).toHaveTextContent('Active: h2');
     });
 
     // Focus H3
     await userEvent.click(focusH3Btn);
-    expect(h3).toHaveFocus();
+    await waitFor(() => expect(h3).toHaveFocus());
     await waitFor(() => {
       expect(activeDisplay).toHaveTextContent('Active: h3');
     });

package/src/components/typography/Paragraph/Paragraph.test.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect,within } from 'storybook/test';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { Paragraph } from './Paragraph';
 
@@ -37,8 +37,8 @@ export const KeyboardNavigation: Story = {
     const paragraph = canvas.getByText(sampleText);
 
     // Paragraph should not be focusable by default
-    paragraph.focus();
-    expect(paragraph).not.toHaveFocus();
+    await userEvent.click(paragraph);
+    await waitFor(() => expect(paragraph).not.toHaveFocus());
   },
 };
 
@@ -67,8 +67,8 @@ export const FocusManagement: Story = {
     const paragraph = canvas.getByText(sampleText);
 
     // When tabIndex is set, paragraph should be focusable
-    paragraph.focus();
-    expect(paragraph).toHaveFocus();
+    await userEvent.click(paragraph);
+    await waitFor(() => expect(paragraph).toHaveFocus());
   },
 };
 
@@ -152,16 +152,9 @@ export const Performance: Story = {
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 
-    const startTime = Date.now();
-
     const paragraph = canvas.getByText(sampleText);
     expect(paragraph).toBeInTheDocument();
 
-    const endTime = Date.now();
-    const renderTime = endTime - startTime;
-
-    // Paragraph should render quickly (under 100ms)
-    expect(renderTime).toBeLessThan(100);
   },
 };
 

package/src/components/typography/Text/Text.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import type { Theme} from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
 import { alpha,Typography } from '@mui/material';
 import { styled } from '@mui/material/styles';
 import React from 'react';
@@ -26,6 +26,86 @@ const getColorFromTheme = (theme: Theme, color: string) => {
   return colorMap[color] || theme.palette.text.primary;
 };
 
+const SIZE_MAP: Record<string, { fontSize: string; lineHeight: number }> = {
+  xs: { fontSize: '0.75rem', lineHeight: 1.2 },
+  sm: { fontSize: '0.875rem', lineHeight: 1.3 },
+  md: { fontSize: '1rem', lineHeight: 1.5 },
+  lg: { fontSize: '1.125rem', lineHeight: 1.4 },
+  xl: { fontSize: '1.25rem', lineHeight: 1.3 },
+};
+
+const WEIGHT_MAP: Record<string, number> = {
+  light: 300,
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+};
+
+interface TextStyleArgs {
+  theme: Theme;
+  customVariant?: string;
+  customColor?: string;
+  customSize?: string;
+  customWeight?: string;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+}
+
+// underline and strikethrough combine into one declaration rather than one
+// winning over the other.
+const decorationFor = (underline?: boolean, strikethrough?: boolean): string =>
+  [underline && 'underline', strikethrough && 'line-through'].filter(Boolean).join(' ') || 'none';
+
+const baseTextStyles = (theme: Theme, a: TextStyleArgs): CSSObject => ({
+  color: getColorFromTheme(theme, a.customColor ?? 'neutral'),
+  fontSize: SIZE_MAP[a.customSize ?? 'md']?.fontSize,
+  lineHeight: SIZE_MAP[a.customSize ?? 'md']?.lineHeight,
+  fontWeight: WEIGHT_MAP[a.customWeight ?? 'normal'],
+  fontStyle: a.italic ? 'italic' : 'normal',
+  textDecoration: decorationFor(a.underline, a.strikethrough),
+  transition: 'all 0.2s ease',
+});
+
+// Captions and code shrink relative to the body scale, but only at the default
+// size — an explicit size wins.
+const sizeOverride = (customSize: string | undefined, atDefault: string): string | undefined =>
+  (customSize ?? 'md') === 'md' ? atDefault : SIZE_MAP[customSize ?? 'md']?.fontSize;
+
+const textVariantStyles = (theme: Theme, a: TextStyleArgs, base: CSSObject): CSSObject => {
+  const weight = a.customWeight ?? 'normal';
+
+  switch (a.customVariant) {
+    case 'heading':
+      return {
+        ...base,
+        fontFamily: theme.typography.h4.fontFamily,
+        fontWeight: weight === 'normal' ? 600 : WEIGHT_MAP[weight],
+        letterSpacing: '-0.01em',
+      };
+    case 'caption':
+      return {
+        ...base,
+        fontSize: sizeOverride(a.customSize, '0.75rem'),
+        opacity: 0.8,
+        letterSpacing: '0.02em',
+      };
+    case 'code':
+      return {
+        ...base,
+        fontFamily: 'Monaco, Menlo, "Ubuntu Mono", "Courier New", monospace',
+        fontSize: sizeOverride(a.customSize, '0.875rem'),
+        backgroundColor: alpha(theme.palette.primary.main, 0.08),
+        padding: '2px 6px',
+        borderRadius: theme.shape.borderRadius / 2,
+        border: `1px solid ${alpha(theme.palette.primary.main, 0.12)}`,
+      };
+    default:
+      return { ...base, fontFamily: theme.typography.body1.fontFamily };
+  }
+};
+
 const StyledText = styled(Typography, {
   shouldForwardProp: (prop) =>
     ![
@@ -45,82 +125,9 @@ const StyledText = styled(Typography, {
   italic?: boolean;
   underline?: boolean;
   strikethrough?: boolean;
-}>(({
-  theme,
-  customVariant,
-  customColor = 'neutral',
-  customSize = 'md',
-  customWeight = 'normal',
-  italic,
-  underline,
-  strikethrough,
-}) => {
-  const textColor = getColorFromTheme(theme, customColor);
-
-  // Size mapping
-  const sizeMap = {
-    xs: { fontSize: '0.75rem', lineHeight: 1.2 },
-    sm: { fontSize: '0.875rem', lineHeight: 1.3 },
-    md: { fontSize: '1rem', lineHeight: 1.5 },
-    lg: { fontSize: '1.125rem', lineHeight: 1.4 },
-    xl: { fontSize: '1.25rem', lineHeight: 1.3 },
-  };
-
-  // Weight mapping
-  const weightMap = {
-    light: 300,
-    normal: 400,
-    medium: 500,
-    semibold: 600,
-    bold: 700,
-  };
-
-  // Base styles
-  const baseStyles = {
-    color: textColor,
-    fontSize: sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
-    lineHeight: sizeMap[customSize as keyof typeof sizeMap]?.lineHeight,
-    fontWeight: weightMap[customWeight as keyof typeof weightMap],
-    fontStyle: italic ? 'italic' : 'normal',
-    textDecoration:
-      [underline && 'underline', strikethrough && 'line-through'].filter(Boolean).join(' ') ||
-      'none',
-    transition: 'all 0.2s ease',
-  };
-
-  // Variant-specific styles
-  const variantStyles = {
-    body: {
-      ...baseStyles,
-      fontFamily: theme.typography.body1.fontFamily,
-    },
-    heading: {
-      ...baseStyles,
-      fontFamily: theme.typography.h4.fontFamily,
-      fontWeight:
-        customWeight === 'normal' ? 600 : weightMap[customWeight as keyof typeof weightMap],
-      letterSpacing: '-0.01em',
-    },
-    caption: {
-      ...baseStyles,
-      fontSize:
-        customSize === 'md' ? '0.75rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
-      opacity: 0.8,
-      letterSpacing: '0.02em',
-    },
-    code: {
-      ...baseStyles,
-      fontFamily: 'Monaco, Menlo, "Ubuntu Mono", "Courier New", monospace',
-      fontSize:
-        customSize === 'md' ? '0.875rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
-      backgroundColor: alpha(theme.palette.primary.main, 0.08),
-      padding: '2px 6px',
-      borderRadius: theme.shape.borderRadius / 2,
-      border: `1px solid ${alpha(theme.palette.primary.main, 0.12)}`,
-    },
-  };
-
-  return variantStyles[customVariant as keyof typeof variantStyles] || variantStyles.body;
+}>((args) => {
+  const { theme } = args;
+  return textVariantStyles(theme, args, baseTextStyles(theme, args));
 });
 
 export const Text = React.forwardRef<HTMLElement, TextProps>(

package/src/components/utility/AnimatedIcon/AnimatedIcon.md

@@ -17,7 +17,7 @@ An animated icon wrapper component that can animate any icon or SVG with various
 
 ```tsx
 import { AnimatedIcon } from '@/components/enhanced/AnimatedIcon';
-import { Settings } from '@mui/icons-material';
+import Settings from '@mui/icons-material/Settings';
 
 // Simple rotating animation
 <AnimatedIcon variant="rotate">
@@ -199,7 +199,7 @@ The AnimatedIcon component includes comprehensive test support through the `data
 ```tsx
 import { render, screen } from '@testing-library/react';
 import { AnimatedIcon } from '@/components/enhanced/AnimatedIcon';
-import { Settings } from '@mui/icons-material';
+import Settings from '@mui/icons-material/Settings';
 
 // In your tests
 test('should render with test ID', () => {
@@ -220,7 +220,7 @@ test('should render with test ID', () => {
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { AnimatedIcon } from '@/components/enhanced/AnimatedIcon';
-import { Favorite } from '@mui/icons-material';
+import Favorite from '@mui/icons-material/Favorite';
 
 test('should handle click events', async () => {
   const handleClick = jest.fn();
@@ -247,7 +247,7 @@ test('should handle click events', async () => {
 ```tsx
 import { render, screen } from '@testing-library/react';
 import { AnimatedIcon } from '@/components/enhanced/AnimatedIcon';
-import { Refresh } from '@mui/icons-material';
+import Refresh from '@mui/icons-material/Refresh';
 
 test('should have proper accessibility attributes', () => {
   render(

package/src/components/utility/AnimatedIcon/AnimatedIcon.stories.tsx

@@ -1,24 +1,22 @@
-import {
-  AccountCircle,
-  AutoAwesome,
-  Bolt,
-  Diamond,
-  Download,
-  Favorite,
-  FlashOn,
-  Home,
-  Lens,
-  Lightbulb,
-  Notifications,
-  Psychology,
-  Refresh,
-  Rocket,
-  Search,
-  Settings,
-  Star,
-  Upload,
-  Waves,
-} from '@mui/icons-material';
+import AccountCircle from '@mui/icons-material/AccountCircle';
+import AutoAwesome from '@mui/icons-material/AutoAwesome';
+import Bolt from '@mui/icons-material/Bolt';
+import Diamond from '@mui/icons-material/Diamond';
+import Download from '@mui/icons-material/Download';
+import Favorite from '@mui/icons-material/Favorite';
+import FlashOn from '@mui/icons-material/FlashOn';
+import Home from '@mui/icons-material/Home';
+import Lens from '@mui/icons-material/Lens';
+import Lightbulb from '@mui/icons-material/Lightbulb';
+import Notifications from '@mui/icons-material/Notifications';
+import Psychology from '@mui/icons-material/Psychology';
+import Refresh from '@mui/icons-material/Refresh';
+import Rocket from '@mui/icons-material/Rocket';
+import Search from '@mui/icons-material/Search';
+import Settings from '@mui/icons-material/Settings';
+import Star from '@mui/icons-material/Star';
+import Upload from '@mui/icons-material/Upload';
+import Waves from '@mui/icons-material/Waves';
 import { Box, Chip,Grid, Paper, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';