@12-apps/ui 1.0.0

package/src/components/form/Label/Label.tsx

@@ -0,0 +1,367 @@
+import {
+  alpha,
+  Box,
+  CircularProgress,
+  Tooltip,
+  Typography,
+  useTheme,
+} from '@mui/material';
+import React, { forwardRef } from 'react';
+
+import type { LabelProps } from './Label.types';
+
+export const Label = forwardRef<globalThis.HTMLLabelElement, LabelProps>(({
+  children,
+  htmlFor,
+  required = false,
+  disabled = false,
+  error = false,
+  variant = 'default',
+  size = 'md',
+  color = 'default',
+  glow = false,
+  pulse = false,
+  ripple = false,
+  loading = false,
+  className,
+  style,
+  tooltip,
+  helperText,
+  asteriskPlacement = 'end',
+  icon,
+  iconPosition = 'start',
+  onClick,
+  onFocus,
+  onBlur,
+  srOnly = false,
+  weight = 'regular',
+  transform = 'none',
+  align = 'left',
+  nowrap = false,
+  truncate = false,
+  dataTestId,
+  ...props
+}, ref) => {
+  const theme = useTheme();
+
+  const getSizeStyles = () => {
+    switch (size) {
+      case 'xs':
+        return {
+          fontSize: '0.75rem',
+          lineHeight: 1.2,
+          padding: theme.spacing(0.25, 0.5),
+        };
+      case 'sm':
+        return {
+          fontSize: '0.875rem',
+          lineHeight: 1.3,
+          padding: theme.spacing(0.5, 0.75),
+        };
+      case 'md':
+        return {
+          fontSize: '1rem',
+          lineHeight: 1.5,
+          padding: theme.spacing(0.75, 1),
+        };
+      case 'lg':
+        return {
+          fontSize: '1.125rem',
+          lineHeight: 1.6,
+          padding: theme.spacing(1, 1.25),
+        };
+      case 'xl':
+        return {
+          fontSize: '1.25rem',
+          lineHeight: 1.7,
+          padding: theme.spacing(1.25, 1.5),
+        };
+      default:
+        return {
+          fontSize: '1rem',
+          lineHeight: 1.5,
+          padding: theme.spacing(0.75, 1),
+        };
+    }
+  };
+
+  const getColorStyles = () => {
+    if (error) {
+      return { color: theme.palette.error.main };
+    }
+    if (disabled) {
+      return { color: theme.palette.text.disabled };
+    }
+    if (color === 'default') {
+      return { color: theme.palette.text.primary };
+    }
+    return { color: theme.palette[color].main };
+  };
+
+  const getVariantStyles = () => {
+    const baseStyles = {
+      display: srOnly ? 'none' : 'inline-flex',
+      alignItems: 'center',
+      gap: theme.spacing(0.5),
+      transition: theme.transitions.create(['all'], {
+        duration: theme.transitions.duration.standard,
+      }),
+      cursor: onClick ? 'pointer' : 'default',
+      textAlign: align,
+      fontWeight: getFontWeight(),
+      textTransform: transform,
+      whiteSpace: nowrap ? 'nowrap' : 'normal',
+      overflow: truncate ? 'hidden' : 'visible',
+      textOverflow: truncate ? 'ellipsis' : 'clip',
+      position: 'relative' as const,
+      ...getSizeStyles(),
+      ...getColorStyles(),
+    };
+
+    const glowStyles = glow ? {
+      textShadow: `0 0 10px ${alpha(getColorStyles().color || theme.palette.primary.main, 0.5)}`,
+    } : {};
+
+    const pulseStyles = pulse ? {
+      animation: 'pulse 2s infinite',
+      '@keyframes pulse': {
+        '0%': { opacity: 1 },
+        '50%': { opacity: 0.6 },
+        '100%': { opacity: 1 },
+      },
+    } : {};
+
+    const rippleStyles = ripple && onClick ? {
+      overflow: 'hidden',
+      '&::after': {
+        content: '""',
+        position: 'absolute',
+        top: '50%',
+        left: '50%',
+        width: 0,
+        height: 0,
+        borderRadius: '50%',
+        backgroundColor: alpha(theme.palette.primary.main, 0.3),
+        transform: 'translate(-50%, -50%)',
+        transition: 'width 0.6s, height 0.6s',
+      },
+      '&:active::after': {
+        width: '300%',
+        height: '300%',
+      },
+    } : {};
+
+    switch (variant) {
+      case 'filled':
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+          backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.1),
+          borderRadius: theme.spacing(0.5),
+          '&:hover': onClick ? {
+            backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.15),
+          } : {},
+        };
+
+      case 'outlined':
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+          border: `1px solid ${alpha(getColorStyles().color || theme.palette.primary.main, 0.5)}`,
+          borderRadius: theme.spacing(0.5),
+          '&:hover': onClick ? {
+            borderColor: getColorStyles().color || theme.palette.primary.main,
+            backgroundColor: alpha(getColorStyles().color || theme.palette.primary.main, 0.05),
+          } : {},
+        };
+
+      case 'glass':
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+          backgroundColor: alpha(theme.palette.background.paper, 0.1),
+          backdropFilter: 'blur(10px)',
+          border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+          borderRadius: theme.spacing(0.5),
+          '&:hover': onClick ? {
+            backgroundColor: alpha(theme.palette.background.paper, 0.15),
+            borderColor: alpha(theme.palette.primary.main, 0.3),
+          } : {},
+        };
+
+      case 'gradient': {
+        const gradientColor = color === 'default' ? 'primary' : color;
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+          background: `linear-gradient(135deg, ${theme.palette[gradientColor].light}, ${theme.palette[gradientColor].main})`,
+          WebkitBackgroundClip: 'text',
+          WebkitTextFillColor: 'transparent',
+          backgroundClip: 'text',
+          '&:hover': onClick ? {
+            background: `linear-gradient(135deg, ${theme.palette[gradientColor].main}, ${theme.palette[gradientColor].dark})`,
+            WebkitBackgroundClip: 'text',
+            WebkitTextFillColor: 'transparent',
+            backgroundClip: 'text',
+          } : {},
+        };
+      }
+
+      case 'minimal':
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+          padding: 0,
+          '&:hover': onClick ? {
+            color: theme.palette.primary.main,
+          } : {},
+        };
+
+      default:
+        return {
+          ...baseStyles,
+          ...glowStyles,
+          ...pulseStyles,
+          ...rippleStyles,
+        };
+    }
+  };
+
+  const getFontWeight = () => {
+    switch (weight) {
+      case 'light': return 300;
+      case 'regular': return 400;
+      case 'medium': return 500;
+      case 'semibold': return 600;
+      case 'bold': return 700;
+      default: return 400;
+    }
+  };
+
+  const renderAsterisk = () => {
+    if (!required) return null;
+    return (
+      <Box
+        component="span"
+        sx={{
+          color: theme.palette.error.main,
+          marginLeft: asteriskPlacement === 'end' ? theme.spacing(0.5) : 0,
+          marginRight: asteriskPlacement === 'start' ? theme.spacing(0.5) : 0,
+        }}
+      >
+        *
+      </Box>
+    );
+  };
+
+  const renderIcon = () => {
+    if (!icon) return null;
+    return (
+      <Box
+        component="span"
+        sx={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          fontSize: 'inherit',
+        }}
+      >
+        {icon}
+      </Box>
+    );
+  };
+
+  const renderLoading = () => {
+    if (!loading) return null;
+    return (
+      <CircularProgress
+        size={getSizeStyles().fontSize}
+        sx={{
+          color: getColorStyles().color,
+          marginLeft: theme.spacing(0.5),
+        }}
+      />
+    );
+  };
+
+  const labelContent = (
+    <Box
+      component="label"
+      ref={ref}
+      htmlFor={htmlFor}
+      onClick={onClick}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      className={className}
+      data-testid={dataTestId}
+      sx={{
+        ...getVariantStyles(),
+        ...style,
+      }}
+      {...props}
+    >
+      {asteriskPlacement === 'start' && renderAsterisk()}
+      {iconPosition === 'start' && renderIcon()}
+      {children}
+      {iconPosition === 'end' && renderIcon()}
+      {asteriskPlacement === 'end' && renderAsterisk()}
+      {renderLoading()}
+    </Box>
+  );
+
+  const wrappedContent = tooltip ? (
+    <Tooltip title={tooltip} arrow>
+      {labelContent}
+    </Tooltip>
+  ) : labelContent;
+
+  return (
+    <>
+      {srOnly && (
+        <Box
+          component="label"
+          htmlFor={htmlFor}
+          data-testid={dataTestId}
+          sx={{
+            position: 'absolute',
+            width: '1px',
+            height: '1px',
+            padding: 0,
+            margin: '-1px',
+            overflow: 'hidden',
+            clip: 'rect(0, 0, 0, 0)',
+            whiteSpace: 'nowrap',
+            border: 0,
+          }}
+        >
+          {children}
+        </Box>
+      )}
+      {!srOnly && wrappedContent}
+      {helperText && !srOnly && (
+        <Typography
+          variant="caption"
+          sx={{
+            display: 'block',
+            color: error ? theme.palette.error.main : theme.palette.text.secondary,
+            marginTop: theme.spacing(0.5),
+            fontSize: '0.75rem',
+          }}
+        >
+          {helperText}
+        </Typography>
+      )}
+    </>
+  );
+});
+
+Label.displayName = 'Label';

package/src/components/form/Label/Label.types.ts

@@ -0,0 +1,35 @@
+import type { CSSProperties, HTMLAttributes,ReactNode } from 'react';
+
+export interface LabelProps extends HTMLAttributes<globalThis.HTMLLabelElement> {
+  children?: ReactNode;
+  htmlFor?: string;
+  required?: boolean;
+  disabled?: boolean;
+  error?: boolean;
+  variant?: 'default' | 'filled' | 'outlined' | 'glass' | 'gradient' | 'minimal';
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  color?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'default';
+  glow?: boolean;
+  pulse?: boolean;
+  glass?: boolean;
+  gradient?: boolean;
+  ripple?: boolean;
+  loading?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  tooltip?: string | ReactNode;
+  helperText?: string;
+  asteriskPlacement?: 'start' | 'end';
+  icon?: ReactNode;
+  iconPosition?: 'start' | 'end';
+  onClick?: (event: React.MouseEvent<globalThis.HTMLLabelElement>) => void;
+  onFocus?: (event: React.FocusEvent<globalThis.HTMLLabelElement>) => void;
+  onBlur?: (event: React.FocusEvent<globalThis.HTMLLabelElement>) => void;
+  srOnly?: boolean;
+  weight?: 'light' | 'regular' | 'medium' | 'semibold' | 'bold';
+  transform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+  align?: 'left' | 'center' | 'right';
+  nowrap?: boolean;
+  truncate?: boolean;
+  dataTestId?: string;
+}

package/src/components/form/Label/index.ts

@@ -0,0 +1,2 @@
+export { Label } from './Label';
+export type { LabelProps } from './Label.types';

package/src/components/form/Menubar/Menubar.md

@@ -0,0 +1,275 @@
+# Menubar Component
+
+A comprehensive navigation component that provides horizontal or vertical menu layouts with nested menu support, keyboard shortcuts, and various visual effects. The Menubar component supports app bar functionality, sticky positioning, logo integration, and extensive customization options with full accessibility compliance.
+
+## Purpose and Use Cases
+
+- **Application Navigation**: Primary navigation bar for web applications
+- **App Bar**: Header navigation with logo, menu items, and user controls
+- **Admin Panels**: Dashboard navigation with nested menu structures
+- **Responsive Design**: Adapts from horizontal to vertical layouts on mobile
+- **Sticky Navigation**: Fixed positioning for persistent access to navigation
+
+## Props Documentation
+
+### Core Props
+
+| Prop          | Type                                                                                   | Default        | Description                                       |
+| ------------- | -------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------- |
+| `items`       | `MenubarItem[]`                                                                        | `[]`           | Array of menu items with nested structure support |
+| `variant`     | `'default' \| 'glass' \| 'gradient' \| 'elevated' \| 'minimal' \| 'bordered'`          | `'default'`    | Visual style variant                              |
+| `size`        | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                                 | `'md'`         | Component size affecting padding and font size    |
+| `color`       | `'primary' \| 'secondary' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'default'` | `'default'`    | Theme color for backgrounds and accents           |
+| `orientation` | `'horizontal' \| 'vertical'`                                                           | `'horizontal'` | Layout orientation                                |
+
+### Layout Props
+
+| Prop          | Type              | Default     | Description                                        |
+| ------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `logo`        | `React.ReactNode` | `undefined` | Logo or brand element displayed at the start       |
+| `endContent`  | `React.ReactNode` | `undefined` | Content displayed at the end (user controls, etc.) |
+| `sticky`      | `boolean`         | `false`     | Enables sticky positioning                         |
+| `transparent` | `boolean`         | `false`     | Transparent background                             |
+| `fullWidth`   | `boolean`         | `false`     | Takes full width of container                      |
+
+### Visual Effects Props
+
+| Prop        | Type      | Default | Description                            |
+| ----------- | --------- | ------- | -------------------------------------- |
+| `glow`      | `boolean` | `false` | Enables glow effect around the menubar |
+| `pulse`     | `boolean` | `false` | Enables subtle pulse animation         |
+| `glass`     | `boolean` | `false` | Enables glass morphism effect          |
+| `gradient`  | `boolean` | `false` | Enables gradient background            |
+| `ripple`    | `boolean` | `false` | Enables ripple effects on interactions |
+| `blur`      | `boolean` | `false` | Enables backdrop blur effect           |
+| `elevation` | `number`  | `0`     | Material-UI elevation for shadow depth |
+
+### State Props
+
+| Prop       | Type      | Default | Description                                    |
+| ---------- | --------- | ------- | ---------------------------------------------- |
+| `loading`  | `boolean` | `false` | Shows loading state with skeleton placeholders |
+| `disabled` | `boolean` | `false` | Disables all interactions                      |
+
+### Event Props
+
+| Prop      | Type                                | Description                          |
+| --------- | ----------------------------------- | ------------------------------------ |
+| `onClick` | `(item: MenubarItem) => void`       | Callback when menu item is clicked   |
+| `onFocus` | `(event: React.FocusEvent) => void` | Callback when menubar receives focus |
+| `onBlur`  | `(event: React.FocusEvent) => void` | Callback when menubar loses focus    |
+
+### MenubarItem Structure
+
+```typescript
+interface MenubarItem {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  shortcut?: string;
+  disabled?: boolean;
+  divider?: boolean;
+  action?: () => void;
+  children?: MenubarItem[];
+}
+```
+
+## Usage Examples
+
+### Basic Menubar
+
+```tsx
+import { Menubar } from '@procurement/ui';
+
+const menuItems = [
+  {
+    id: 'file',
+    label: 'File',
+    children: [
+      { id: 'new', label: 'New', shortcut: '⌘N' },
+      { id: 'open', label: 'Open', shortcut: '⌘O' },
+    ],
+  },
+  {
+    id: 'edit',
+    label: 'Edit',
+    children: [
+      { id: 'cut', label: 'Cut', shortcut: '⌘X' },
+      { id: 'copy', label: 'Copy', shortcut: '⌘C' },
+    ],
+  },
+];
+
+<Menubar items={menuItems} />;
+```
+
+### App Bar with Logo and User Controls
+
+```tsx
+import { Menubar } from '@procurement/ui';
+import { Avatar, IconButton } from '@mui/material';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+
+const Logo = () => (
+  <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+    <img src="/logo.svg" alt="App" width={32} height={32} />
+    <Typography variant="h6">MyApp</Typography>
+  </Box>
+);
+
+const UserControls = () => (
+  <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+    <IconButton color="inherit">
+      <NotificationsIcon />
+    </IconButton>
+    <Avatar>U</Avatar>
+  </Box>
+);
+
+<Menubar
+  items={menuItems}
+  variant="elevated"
+  logo={<Logo />}
+  endContent={<UserControls />}
+  sticky
+/>;
+```
+
+### Glass Effect Menubar
+
+```tsx
+<Menubar
+  items={menuItems}
+  variant="glass"
+  glass
+  blur
+  glow
+  transparent
+  sticky
+  logo={<Logo />}
+  endContent={<UserControls />}
+/>
+```
+
+### Vertical Sidebar Navigation
+
+```tsx
+<Menubar items={menuItems} orientation="vertical" variant="minimal" logo={<Logo />} fullWidth />
+```
+
+## Accessibility Notes
+
+- **Keyboard Navigation**: Full keyboard support with Tab, Enter, Escape, and Arrow keys
+- **Screen Reader Support**: Comprehensive ARIA labels and roles
+- **Focus Management**: Proper focus indication and management
+- **High Contrast**: Compatible with high contrast themes
+- **Reduced Motion**: Respects user's motion preferences
+
+### ARIA Attributes
+
+- `role="menubar"` on the main container
+- `role="menu"` on dropdown menus
+- `role="menuitem"` on individual menu items
+- `aria-haspopup` for items with children
+- `aria-expanded` for dropdown state
+- `aria-label` for accessibility labels
+
+### Keyboard Shortcuts
+
+- **Tab/Shift+Tab**: Navigate between menu items
+- **Enter/Space**: Activate menu item or open dropdown
+- **Escape**: Close open dropdown or exit menu
+- **Arrow Keys**: Navigate within dropdowns
+- **Home/End**: Jump to first/last menu item
+
+## Best Practices
+
+### Design Guidelines
+
+1. **Use appropriate variants**: Choose variants that match your app's design system
+2. **Consistent sizing**: Use consistent sizes across similar navigation elements
+3. **Logo placement**: Place logo at the start for better brand recognition
+4. **User controls**: Group user-related controls at the end
+5. **Visual hierarchy**: Use different variants to establish navigation hierarchy
+
+### Performance Considerations
+
+1. **Lazy loading**: Consider lazy loading for deeply nested menu structures
+2. **Memoization**: Wrap menu items in useMemo for large datasets
+3. **Virtualization**: For extremely large menu lists, consider virtualization
+4. **Effect usage**: Use visual effects sparingly to maintain performance
+
+### Accessibility Best Practices
+
+1. **Meaningful labels**: Ensure all menu items have descriptive labels
+2. **Keyboard support**: Test all functionality with keyboard only
+3. **Screen reader testing**: Test with actual screen readers
+4. **Color contrast**: Ensure sufficient contrast for all text
+5. **Focus indicators**: Maintain clear focus indicators
+
+### Common Patterns
+
+#### Admin Dashboard
+
+```tsx
+<Menubar
+  variant="elevated"
+  logo={<AdminLogo />}
+  endContent={<UserProfile />}
+  items={adminMenuItems}
+  sticky
+/>
+```
+
+#### Marketing Website
+
+```tsx
+<Menubar
+  variant="glass"
+  transparent
+  glass
+  blur
+  items={marketingMenuItems}
+  endContent={<CTAButton />}
+/>
+```
+
+#### Mobile Responsive
+
+```tsx
+// Horizontal on desktop, vertical drawer on mobile
+<Menubar
+  variant="minimal"
+  orientation={isMobile ? 'vertical' : 'horizontal'}
+  fullWidth={isMobile}
+  items={menuItems}
+/>
+```
+
+## Integration with Design Systems
+
+The Menubar component integrates seamlessly with Material-UI's theming system and supports:
+
+- **Custom color palettes**: Uses theme colors for consistent branding
+- **Typography scales**: Adapts to theme typography settings
+- **Spacing system**: Uses theme spacing for consistent layouts
+- **Dark mode**: Automatic dark mode support through theme
+- **Custom breakpoints**: Respects theme breakpoint configuration
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Menu items not clickable**: Ensure `action` callbacks are provided or `onClick` handler is set
+2. **Dropdowns not opening**: Check that `children` array is properly structured
+3. **Styling conflicts**: Verify theme integration and CSS specificity
+4. **Mobile responsiveness**: Test orientation changes and viewport sizes
+5. **Performance issues**: Monitor re-renders with large menu structures
+
+### Debug Tips
+
+- Use browser dev tools to inspect ARIA attributes
+- Test keyboard navigation in different browsers
+- Verify focus management with Tab navigation
+- Check color contrast with accessibility tools
+- Test with actual screen readers for comprehensive accessibility verification