@12-apps/ui 1.4.0 → 1.5.0

package/src/components/form/Menubar/Menubar.hooks.ts

@@ -0,0 +1,41 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type { MenubarItem, MenubarProps } from './Menubar.types';
+
+/**
+ * Which dropdown is open, and the buttons that opened them.
+ *
+ * The anchors are kept in a ref rather than state because closing needs to
+ * return focus to the button that opened the menu, and that lookup must not
+ * itself cause a render.
+ */
+export const useMenubarMenus = (onClick?: MenubarProps['onClick']) => {
+  const [activeMenu, setActiveMenu] = useState<string | null>(null);
+  const menuRefs = useRef<{ [key: string]: HTMLElement | null }>({});
+
+  const handleMenuOpen = useCallback((itemId: string, anchorEl: HTMLElement) => {
+    setActiveMenu(itemId);
+    menuRefs.current[itemId] = anchorEl;
+  }, []);
+
+  const handleMenuClose = useCallback(() => {
+    setActiveMenu((previous) => {
+      // Return focus to the button that opened the menu.
+      if (previous && menuRefs.current[previous]) {
+        menuRefs.current[previous].focus();
+      }
+      return null;
+    });
+  }, []);
+
+  const handleItemClick = useCallback(
+    (item: MenubarItem) => {
+      item.action?.();
+      onClick?.(item);
+      handleMenuClose();
+    },
+    [onClick, handleMenuClose],
+  );
+
+  return { activeMenu, menuRefs, handleMenuOpen, handleMenuClose, handleItemClick };
+};

package/src/components/form/Menubar/Menubar.item.tsx

@@ -0,0 +1,121 @@
+import KeyboardArrowDownIcon from '@mui/icons-material/KeyboardArrowDown';
+import {
+  Box,
+  Button,
+  Chip,
+  Divider,
+  ListItemIcon,
+  ListItemText,
+  Menu,
+  MenuItem,
+  useTheme,
+} from '@mui/material';
+import React from 'react';
+
+import { sizeStyles } from './Menubar.styles';
+import type { MenubarItem, MenubarProps } from './Menubar.types';
+
+export interface MenubarItemViewProps {
+  item: MenubarItem;
+  size: NonNullable<MenubarProps['size']>;
+  disabled: boolean;
+  isOpen: boolean;
+  anchorEl: HTMLElement | null;
+  onOpen: (itemId: string, anchorEl: HTMLElement) => void;
+  onActivate: (item: MenubarItem) => void;
+  onClose: () => void;
+  onFocus?: React.FocusEventHandler;
+  onBlur?: React.FocusEventHandler;
+}
+
+/** One row of an open menu: its icon, its label, and its shortcut hint. */
+const DropdownItem: React.FC<{ child: MenubarItem; onActivate: (item: MenubarItem) => void }> = ({
+  child,
+  onActivate,
+}) =>
+  child.divider ? (
+    <Divider />
+  ) : (
+    <MenuItem onClick={() => onActivate(child)} disabled={child.disabled}>
+      {child.icon && <ListItemIcon>{child.icon}</ListItemIcon>}
+      <ListItemText>{child.label}</ListItemText>
+      {child.shortcut && (
+        <Chip
+          label={child.shortcut}
+          size="small"
+          variant="outlined"
+          sx={{ ml: 2, height: 20, fontSize: '0.7rem' }}
+        />
+      )}
+    </MenuItem>
+  );
+
+/**
+ * A top-level menubar entry. An entry with children opens its dropdown; one
+ * without acts immediately — a decision the click and keyboard paths both need,
+ * so it is made once here rather than in each handler.
+ */
+export const MenubarItemView: React.FC<MenubarItemViewProps> = ({
+  item,
+  size,
+  disabled,
+  isOpen,
+  anchorEl,
+  onOpen,
+  onActivate,
+  onClose,
+  onFocus,
+  onBlur,
+}) => {
+  const theme = useTheme();
+  const hasChildren = Boolean(item.children && item.children.length > 0);
+
+  const activate = (target: HTMLElement) => {
+    if (hasChildren) {
+      onOpen(item.id, target);
+    } else {
+      onActivate(item);
+    }
+  };
+
+  return (
+    <Box>
+      <Button
+        data-testid={`menubar-button-${item.id}`}
+        onClick={(e) => activate(e.currentTarget)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            activate(e.currentTarget);
+          }
+        }}
+        // Keeping focus on mousedown is what lets handleMenuClose return it here.
+        onMouseDown={(e) => e.preventDefault()}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        disabled={item.disabled || disabled}
+        startIcon={item.icon}
+        endIcon={hasChildren ? <KeyboardArrowDownIcon /> : null}
+        aria-haspopup={hasChildren ? 'menu' : undefined}
+        aria-expanded={hasChildren ? isOpen : undefined}
+        sx={{ color: 'inherit', textTransform: 'none', ...sizeStyles(theme, size) }}
+      >
+        {item.label}
+      </Button>
+
+      {hasChildren && (
+        <Menu
+          anchorEl={anchorEl}
+          open={isOpen}
+          onClose={onClose}
+          autoFocus
+          PaperProps={{ sx: { minWidth: 200, mt: 1 } }}
+        >
+          {item.children?.map((child) => (
+            <DropdownItem key={child.id} child={child} onActivate={onActivate} />
+          ))}
+        </Menu>
+      )}
+    </Box>
+  );
+};

package/src/components/form/Menubar/Menubar.separator.tsx

@@ -0,0 +1,25 @@
+import { Divider } from '@mui/material';
+import React from 'react';
+
+import type { MenubarSeparatorProps } from './Menubar.types';
+
+/**
+ * The rule between two entries. Its own orientation is the bar's turned ninety
+ * degrees: a horizontal bar is divided by vertical rules.
+ */
+export const MenubarSeparator: React.FC<MenubarSeparatorProps> = ({
+  orientation = 'horizontal',
+  className,
+  style,
+}) => (
+  <Divider
+    orientation={orientation === 'horizontal' ? 'vertical' : 'horizontal'}
+    flexItem
+    className={className}
+    sx={{
+      mx: orientation === 'horizontal' ? 1 : 0,
+      my: orientation === 'vertical' ? 1 : 0,
+      ...style,
+    }}
+  />
+);

package/src/components/form/Menubar/Menubar.styles.ts

@@ -0,0 +1,110 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+
+import type { MenubarProps } from './Menubar.types';
+
+type Size = NonNullable<MenubarProps['size']>;
+type Variant = NonNullable<MenubarProps['variant']>;
+type Color = NonNullable<MenubarProps['color']>;
+
+const SIZES: Record<Size, (theme: Theme) => CSSObject> = {
+  xs: (theme) => ({ minHeight: 40, fontSize: '0.75rem', padding: theme.spacing(0.5, 1) }),
+  sm: (theme) => ({ minHeight: 48, fontSize: '0.875rem', padding: theme.spacing(0.75, 1.5) }),
+  md: (theme) => ({ minHeight: 56, fontSize: '1rem', padding: theme.spacing(1, 2) }),
+  lg: (theme) => ({ minHeight: 64, fontSize: '1.125rem', padding: theme.spacing(1.25, 2.5) }),
+  xl: (theme) => ({ minHeight: 72, fontSize: '1.25rem', padding: theme.spacing(1.5, 3) }),
+};
+
+export const sizeStyles = (theme: Theme, size: Size): CSSObject =>
+  (SIZES[size] ?? SIZES.md)(theme);
+
+/** `default` is not a palette entry — it means the paper surface and its text. */
+const accentOf = (theme: Theme, color: Color) =>
+  color === 'default' ? theme.palette.primary.main : theme.palette[color].main;
+
+const colorStyles = (theme: Theme, color: Color, transparent: boolean): CSSObject => {
+  const surface =
+    color === 'default'
+      ? { backgroundColor: theme.palette.background.paper, color: theme.palette.text.primary }
+      : { backgroundColor: theme.palette[color].main, color: theme.palette[color].contrastText };
+
+  return transparent ? { ...surface, backgroundColor: 'transparent' } : surface;
+};
+
+interface MenubarStyleFlags {
+  variant: Variant;
+  size: Size;
+  color: Color;
+  glow: boolean;
+  pulse: boolean;
+  glass: boolean;
+  gradient: boolean;
+  blur: boolean;
+  transparent: boolean;
+  elevation: number;
+}
+
+/**
+ * Each variant's own additions to the shared bar. The `glass` and `gradient`
+ * arms deliberately do not take the blur spread: glass sets its own
+ * backdropFilter, and a blurred gradient loses the gradient.
+ */
+const SURFACES: Record<Variant, (theme: Theme, flags: MenubarStyleFlags) => CSSObject> = {
+  glass: (theme, { glass }) => ({
+    backgroundColor: alpha(theme.palette.background.paper, glass ? 0.1 : 0.8),
+    backdropFilter: 'blur(20px)',
+    borderBottom: `1px solid ${alpha(theme.palette.divider, 0.1)}`,
+  }),
+
+  gradient: (theme, { color, gradient }) => {
+    const key = color === 'default' ? 'primary' : color;
+    return {
+      background: gradient
+        ? `linear-gradient(135deg, ${theme.palette[key].light}, ${theme.palette[key].dark})`
+        : theme.palette[key].main,
+      color: theme.palette[key].contrastText,
+    };
+  },
+
+  elevated: (theme, { blur, elevation }) => ({
+    ...(blur && { backdropFilter: 'blur(10px)' }),
+    boxShadow: theme.shadows[elevation],
+  }),
+
+  minimal: (_theme, { blur }) => ({
+    ...(blur && { backdropFilter: 'blur(10px)' }),
+    boxShadow: 'none',
+    borderBottom: 'none',
+  }),
+
+  bordered: (theme, { blur, color }) => ({
+    ...(blur && { backdropFilter: 'blur(10px)' }),
+    borderBottom: `2px solid ${
+      color === 'default' ? theme.palette.divider : theme.palette[color].main
+    }`,
+  }),
+
+  default: (_theme, { blur }) => ({ ...(blur && { backdropFilter: 'blur(10px)' }) }),
+};
+
+export const barStyles = (theme: Theme, flags: MenubarStyleFlags): CSSObject => {
+  const { variant, size, color, glow, pulse, transparent } = flags;
+
+  return {
+    transition: theme.transitions.create(['all'], {
+      duration: theme.transitions.duration.standard,
+    }),
+    ...sizeStyles(theme, size),
+    ...colorStyles(theme, color, transparent),
+    ...(glow && { boxShadow: `0 0 20px ${alpha(accentOf(theme, color), 0.4)}` }),
+    ...(pulse && {
+      animation: 'pulse 2s infinite',
+      '@keyframes pulse': {
+        '0%': { opacity: 1 },
+        '50%': { opacity: 0.8 },
+        '100%': { opacity: 1 },
+      },
+    }),
+    ...(SURFACES[variant] ?? SURFACES.default)(theme, flags),
+  };
+};

package/src/components/form/Menubar/Menubar.toolbar.tsx

@@ -0,0 +1,103 @@
+import { Box, CircularProgress, Toolbar } from '@mui/material';
+import type { CSSObject } from '@mui/material';
+import React from 'react';
+
+import { MenubarItemView } from './Menubar.item';
+import { MenubarSeparator } from './Menubar.separator';
+import type { MenubarItem, MenubarProps } from './Menubar.types';
+
+export interface MenubarToolbarProps {
+  barSx: CSSObject;
+  items: MenubarItem[];
+  size: NonNullable<MenubarProps['size']>;
+  orientation: NonNullable<MenubarProps['orientation']>;
+  disabled: boolean;
+  loading: boolean;
+  logo?: React.ReactNode;
+  endContent?: React.ReactNode;
+  fullWidth: boolean;
+  activeMenu: string | null;
+  menuRefs: React.MutableRefObject<{ [key: string]: HTMLElement | null }>;
+  onOpen: (itemId: string, anchorEl: HTMLElement) => void;
+  onActivate: (item: MenubarItem) => void;
+  onClose: () => void;
+  onFocus?: React.FocusEventHandler;
+  onBlur?: React.FocusEventHandler;
+}
+
+/**
+ * The bar's contents: an optional logo, the entries themselves, and whatever the
+ * caller hangs off the end. Shared by both orientations — only the element
+ * wrapping it differs.
+ */
+export const MenubarToolbar: React.FC<MenubarToolbarProps> = ({
+  barSx,
+  items,
+  size,
+  orientation,
+  disabled,
+  loading,
+  logo,
+  endContent,
+  fullWidth,
+  activeMenu,
+  menuRefs,
+  onOpen,
+  onActivate,
+  onClose,
+  onFocus,
+  onBlur,
+}) => {
+  const isVertical = orientation === 'vertical';
+
+  return (
+    <Toolbar
+      role="toolbar"
+      aria-label="Main navigation"
+      sx={{
+        ...barSx,
+        width: fullWidth ? '100%' : 'auto',
+        flexDirection: isVertical ? 'column' : 'row',
+        alignItems: isVertical ? 'flex-start' : 'center',
+        gap: 1,
+      }}
+    >
+      {logo && <Box sx={{ mr: 2, display: 'flex', alignItems: 'center' }}>{logo}</Box>}
+
+      {loading ? (
+        <CircularProgress size={20} color="inherit" />
+      ) : (
+        <Box
+          sx={{
+            display: 'flex',
+            flexDirection: isVertical ? 'column' : 'row',
+            gap: isVertical ? 0.5 : 1,
+            flex: 1,
+          }}
+        >
+          {items.map((item) =>
+            item.divider ? (
+              <MenubarSeparator key={item.id} orientation={orientation} />
+            ) : (
+              <MenubarItemView
+                key={item.id}
+                item={item}
+                size={size}
+                disabled={disabled}
+                isOpen={activeMenu === item.id}
+                anchorEl={menuRefs.current[item.id] ?? null}
+                onOpen={onOpen}
+                onActivate={onActivate}
+                onClose={onClose}
+                onFocus={onFocus}
+                onBlur={onBlur}
+              />
+            ),
+          )}
+        </Box>
+      )}
+
+      {endContent && <Box sx={{ ml: 'auto' }}>{endContent}</Box>}
+    </Toolbar>
+  );
+};