@veracity/vui 2.30.0-beta.0 → 2.30.0

package/src/sidemenuV2/sidemenuV2.tsx

@@ -0,0 +1,302 @@
+import { useMemo, useCallback } from 'react'
+
+import Box from '../box'
+import Button from '../button'
+import { useStyleConfig, vui } from '../core'
+import type { VuiComponent } from '../core'
+import Icon from '../icon'
+import { cs, isActivePath, generateMenuItemId } from '../utils'
+import { collapsedWidth, expandedWidth } from './consts'
+import { SidemenuStateProvider, useSidemenuContext } from './context'
+import SidemenuItemV2 from './sidemenuItemV2'
+import type { SidemenuItemV2Props, SidemenuV2Props } from './sidemenuV2.types'
+
+// Re-export context provider and hook
+export { SidemenuStateProvider, useSidemenuContext }
+
+/** A collapsible side menu for navigation. */
+export const SidemenuV2 = vui<'div', SidemenuV2Props>((props, ref) => {
+  const {
+    isExpandedInitial = true, // Uncontrolled: only affects initial state
+    size,
+    variant = 'light',
+    onExpandedChange,
+  } = props
+
+  return (
+    <SidemenuStateProvider
+      isExpandedInitial={isExpandedInitial}
+      onExpandedChange={onExpandedChange}
+      variant={variant}
+      size={size}
+      isDark={variant === 'dark'}
+    >
+      <SidemenuInner {...props} ref={ref} />
+    </SidemenuStateProvider>
+  )
+}) as VuiComponent<'div', SidemenuV2Props> & {
+  Item: typeof SidemenuItemV2
+}
+
+// Inner component that uses context
+const SidemenuInner = vui<'div', SidemenuV2Props>((props, ref) => {
+  const {
+    children,
+    className,
+    items,
+    shouldExpand, // Callback: fine-grained control over expansion
+    isSticky = false,
+    size,
+    variant = 'light',
+    width = expandedWidth,
+    top,
+    onNavigate,
+    ...rest
+  } = props
+
+  // Get state from context
+  const context = useSidemenuContext()
+  const { isMenuExpanded = true, setIsExpanded } = context || {}
+
+  // Get styles configuration early
+  const styles = useStyleConfig('SidemenuV2', props)
+
+  // Memoized boolean conditions
+  const conditions = useMemo(
+    () => ({
+      isDark: variant === 'dark',
+      hasItems: !!items,
+      shouldShowItems: !!items && items.length > 0,
+      isMenuSticky: isSticky,
+      isMenuExpanded: isMenuExpanded,
+    }),
+    [variant, items, isSticky, isMenuExpanded],
+  )
+
+  // Memoized computed values for styling and behavior
+  const computedValues = useMemo(() => {
+    // Get toggle button config from theme
+    const toggleButtonTheme = styles.toggleButton || {}
+    const currentSize = size || 'md' // Ensure we have a valid size
+    const sizeStyles = (styles as any).sizes?.[currentSize] || {}
+    const toggleButtonSizeTheme = sizeStyles.toggleButton || {}
+
+    // Merge base theme with size-specific overrides
+    const toggleConfig = {
+      baseHeight: toggleButtonSizeTheme.baseHeight || toggleButtonTheme.baseHeight || 52,
+      basePadding: toggleButtonSizeTheme.basePadding || toggleButtonTheme.basePadding || 2,
+      expandedPaddingMultiplier: toggleButtonTheme.expandedPaddingMultiplier || 5,
+      expandedWidth: toggleButtonTheme.expandedWidth || '52px',
+      collapsedWidth: toggleButtonTheme.collapsedWidth || '100%',
+    }
+
+    // Helper function for consistent top position formatting
+    const getMenuTopPosition = (isSticky: boolean, topValue?: any): string => {
+      if (!isSticky) return 'auto'
+
+      if (typeof topValue === 'string') return topValue
+      if (typeof topValue === 'number') return `${topValue}px`
+
+      return '0px' // fallback for undefined/null/complex types
+    }
+
+    return {
+      menuWidth: conditions.isMenuExpanded ? width : collapsedWidth,
+      toggleArrowDirection: conditions.isMenuExpanded ? 'Left' : 'Right',
+      toggleButtonJustification: conditions.isMenuExpanded ? 'flex-end' : 'center',
+      toggleButtonVariant: styles.toggleButton?.variant || (conditions.isDark ? 'tertiaryLight' : 'tertiaryDark'),
+      toggleAriaLabel: conditions.isMenuExpanded ? 'Collapse menu' : 'Expand menu',
+      toggleButtonPadding: toggleConfig.basePadding,
+      toggleButtonVerticalPadding: conditions.isMenuExpanded
+        ? toggleConfig.basePadding * toggleConfig.expandedPaddingMultiplier
+        : toggleConfig.basePadding,
+      toggleButtonHeight: toggleConfig.baseHeight,
+      toggleButtonWidth: conditions.isMenuExpanded ? toggleConfig.expandedWidth : toggleConfig.collapsedWidth,
+      menuPosition: conditions.isMenuSticky ? 'sticky' : 'static',
+      menuTopPosition: getMenuTopPosition(conditions.isMenuSticky, top),
+    }
+  }, [conditions, width, top, styles, size])
+
+  // Memoized icon name
+  const toggleIcon = useMemo(
+    () => `falArrow${computedValues.toggleArrowDirection}` as const,
+    [computedValues.toggleArrowDirection],
+  )
+
+  // Stable callback for toggle (simplified)
+  const handleToggle = useCallback(() => {
+    const newExpandedState = !conditions.isMenuExpanded
+
+    // Check if expansion should be allowed via callback
+    if (shouldExpand && !shouldExpand('toggle', conditions.isMenuExpanded)) {
+      return // Block the toggle
+    }
+
+    // Update state via context
+    setIsExpanded?.(newExpandedState)
+  }, [conditions.isMenuExpanded, shouldExpand, setIsExpanded])
+
+  // Stable callback for item click - with expansion control
+  const handleItemClick = useCallback(
+    (item: SidemenuItemV2Props) => {
+      // Early return for clarity
+      if (shouldExpand && item?.path) {
+        const shouldExpandOnNav = shouldExpand('navigation', conditions.isMenuExpanded)
+        if (typeof shouldExpandOnNav === 'boolean' && shouldExpandOnNav !== conditions.isMenuExpanded) {
+          setIsExpanded?.(shouldExpandOnNav)
+        }
+      }
+      // Call item click handler
+      item?.onClick?.()
+      // Navigate if path exists
+      if (item?.path) onNavigate?.(item.path)
+    },
+    [onNavigate, shouldExpand, conditions.isMenuExpanded, setIsExpanded],
+  )
+
+  // Create stable item click handlers
+  const itemClickHandlers = useMemo(() => {
+    return (items ?? []).reduce<Record<string, () => void>>((handlers, item, index) => {
+      const itemId = item.itemId || item.path || generateMenuItemId(item.title, item.level || 0) || `item-${index}`
+      handlers[itemId] = () => handleItemClick(item)
+      return handlers
+    }, {})
+  }, [items, handleItemClick])
+
+  // Memoized items rendering
+  const renderedItems = useMemo(() => {
+    if (!conditions.shouldShowItems) return children
+
+    return items?.map?.((item: SidemenuItemV2Props, index: number) => {
+      // Use consistent itemId generation that matches the component's logic
+      const itemId = item.itemId || item.path || generateMenuItemId(item.title, item.level || 0) || `item-${index}`
+
+      // Use explicit isActive prop if provided, otherwise calculate from path
+      const calculatedIsActive = item.isActive !== undefined ? item.isActive : isActivePath(item?.path || '')
+
+      return (
+        <SidemenuItemV2
+          isActive={calculatedIsActive}
+          onBottom={item.onBottom}
+          key={itemId}
+          itemId={itemId}
+          level={item.level || 0}
+          {...item}
+          onClick={itemClickHandlers[itemId]}
+        />
+      )
+    })
+  }, [conditions.shouldShowItems, conditions.isMenuExpanded, items, children, itemClickHandlers])
+
+  // Memoized CSS class names
+  const cssClasses = useMemo(
+    () =>
+      cs(
+        'vui-sidemenu',
+        `vui-sidemenu--${variant}`,
+        conditions.isMenuExpanded && 'vui-sidemenu--expanded',
+        !conditions.isMenuExpanded && 'vui-sidemenu--collapsed',
+        conditions.isDark && 'vui-sidemenu--dark',
+        conditions.isMenuSticky && 'vui-sidemenu--sticky',
+        className,
+      ),
+    [variant, conditions, className],
+  )
+
+  // Memoized container props
+  const containerProps = useMemo(
+    () => ({
+      className: cssClasses,
+      flexDirection: 'column' as const,
+      overflowX: 'hidden' as const,
+      position: computedValues.menuPosition,
+      ref,
+      top: computedValues.menuTopPosition,
+      transitionDuration: 'normal' as const,
+      transitionProperty: 'width' as const,
+      w: computedValues.menuWidth,
+
+      ...styles.container,
+      ...rest,
+    }),
+    [
+      cssClasses,
+      computedValues.menuPosition,
+      computedValues.menuTopPosition,
+      computedValues.menuWidth,
+      ref,
+      styles.container,
+      rest,
+    ],
+  )
+
+  // Memoized toggle button props with complete dependencies
+  const toggleButtonProps = useMemo(
+    () => ({
+      'aria-expanded': conditions.isMenuExpanded,
+      'aria-label': computedValues.toggleAriaLabel,
+      border: 0,
+      borderRadius: 0,
+      justifyContent: computedValues.toggleButtonJustification,
+      minHeight: `${computedValues.toggleButtonHeight}px`,
+      minWidth: 0,
+      onClick: handleToggle,
+      px: computedValues.toggleButtonPadding,
+      py: `${computedValues.toggleButtonVerticalPadding}px`,
+      size: 'lg' as const,
+      variant: computedValues.toggleButtonVariant,
+      w: computedValues.toggleButtonWidth,
+      flexShrink: 0,
+      transition: styles.toggleButton?.transition || 'padding 0.2s ease-in-out, width 0.2s ease-in-out',
+    }),
+    [
+      computedValues.toggleAriaLabel,
+      computedValues.toggleButtonJustification,
+      computedValues.toggleButtonVariant,
+      computedValues.toggleButtonPadding,
+      computedValues.toggleButtonVerticalPadding,
+      computedValues.toggleButtonHeight,
+      computedValues.toggleButtonWidth,
+      conditions.isMenuExpanded,
+      handleToggle,
+      styles.toggleButton,
+    ],
+  )
+
+  return (
+    <Box elevation="3" {...containerProps}>
+      <Box
+        className="vui-sidemenu-content"
+        flexDirection="column"
+        flexGrow={1}
+        justifyContent="flex-start"
+        minW={expandedWidth}
+        overflowX="hidden"
+        overflowY="auto"
+        w="100%"
+        role="navigation"
+        aria-label="Main navigation"
+      >
+        {renderedItems}
+      </Box>
+
+      <Box
+        className="vui-sidemenu-bottom"
+        justifyContent={conditions.isMenuExpanded ? 'flex-end' : 'flex-start'}
+        borderTop="1px solid sandstone.main"
+      >
+        <Button {...toggleButtonProps} key={'sidemenu-toggle-button'}>
+          <Icon name={toggleIcon} size="sm" aria-hidden="true" />
+        </Button>
+      </Box>
+    </Box>
+  )
+}) as VuiComponent<'div', SidemenuV2Props> & {
+  // Top: typeof SidemenuTop
+  Item: typeof SidemenuItemV2
+}
+
+SidemenuV2.Item = SidemenuItemV2
+SidemenuV2.displayName = 'SidemenuV2'
+
+export default SidemenuV2

package/src/sidemenuV2/sidemenuV2.types.ts

@@ -0,0 +1,330 @@
+import type { ReactNode, ComponentProps } from 'react'
+
+import type { BadgeProps } from '../badge/badge.types'
+import type { BoxProps } from '../box'
+import type { IconProp } from '../icon'
+import type { SystemProps } from '../system'
+import type { ThemingProps } from '../theme'
+
+export type SidemenuOrientationV2 = 'vertical' | 'horizontal'
+
+export type SidemenuSizeV2 = 'md'
+
+export type SidemenuVariantV2 = 'default' | 'dark' | 'light'
+
+export type SidemenuCollapseModeV2 = 'auto' | 'manual' | 'responsive'
+
+export type SidemenuV2Props = SystemProps &
+  ThemingProps<'Sidemenu'> & {
+    /** Collection of menu items */
+    items?: SidemenuItemV2Props[]
+    /** Initial expansion state (uncontrolled) @default true */
+    isExpandedInitial?: boolean
+    /** Callback to control when expansion should be allowed */
+    shouldExpand?: (trigger: 'toggle' | 'navigation', currentState: boolean) => boolean
+    /** Whether the menu is sticky @default false */
+    isSticky?: boolean
+    /** External callback for navigation to the item path, could be a custom function or React Router hook: https://reactrouter.com/en/main/hooks/use-navigate */
+    onNavigate?: (to: string, item?: SidemenuItemV2Props) => void
+    /** Custom navigation component for different routing libraries */
+    NavigationComponent?: React.ComponentType<{ to: string; children: ReactNode }>
+    /** Width of the container when the side menu is expanded @default 280 */
+    width?: number
+    /** Width of the container when collapsed @default 64 */
+    collapsedWidth?: number
+    /** Sidemenu orientation @default 'vertical' */
+    orientation?: SidemenuOrientationV2
+    /** Sidemenu size variant @default 'md' */
+    size?: SidemenuSizeV2
+    /** Sidemenu visual variant @default 'default' */
+    variant?: SidemenuVariantV2
+    /** Collapse behavior @default 'manual' */
+    collapseMode?: SidemenuCollapseModeV2
+    /** Breakpoint for responsive collapse */
+    collapseBreakpoint?: string
+    /** Custom header content */
+    header?: ReactNode
+    /** Custom footer content */
+    footer?: ReactNode
+    /** Show tooltips on collapsed items @default true */
+    showTooltips?: boolean
+    /** Allow multiple expanded groups @default false */
+    allowMultipleExpanded?: boolean
+    /** Callback when expansion state changes */
+    onExpandedChange?: (isExpanded: boolean) => void
+    /** Callback when an item is selected */
+    onItemSelect?: (item: SidemenuItemV2Props) => void
+    /** ARIA label for the sidemenu */
+    'aria-label'?: string
+    /** ARIA labelledby for the sidemenu */
+    'aria-labelledby'?: string
+    /** Test ID for automated testing */
+    'data-testid'?: string
+    /** Enable keyboard navigation @default true */
+    enableKeyboardNavigation?: boolean
+    /** Auto-collapse siblings when expanding @default false */
+    autoCollapseSiblings?: boolean
+    /** Loading state @default false */
+    isLoading?: boolean
+    /** Error state */
+    error?: string | ReactNode
+    /** Empty state content */
+    emptyContent?: ReactNode
+    /** Animation duration in milliseconds @default 250 */
+    animationDuration?: number
+    /** Disable animations @default false */
+    disableAnimation?: boolean
+  }
+
+export type SidemenuItemBadgeV2Props = {
+  /** Badge content */
+  content?: string | number
+  /** Badge variant @default 'default' */
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info'
+  /** Show badge as dot @default false */
+  isDot?: boolean
+  /** Maximum count to display @default 99 */
+  maxCount?: number
+}
+
+export type SidemenuItemV2Props = BoxProps & {
+  /** Custom class name */
+  className?: string
+  /** Children (submenu items) */
+  children?: ReactNode
+  /** Icon name or component */
+  icon?: IconProp
+  /** Icon size @default 'md' */
+  iconSize?: 'md' | 'sm' | 'lg'
+  /** Whether the item is active */
+  isActive?: boolean
+  /** Whether the item is expanded vertically */
+  isExpanded?: boolean
+  /** Unique identifier for submenu state management */
+  itemId?: string
+  /** Whether the item is disabled @default false */
+  disabled?: boolean
+  /** Whether the item is loading @default false */
+  isLoading?: boolean
+  /** On click callback */
+  onClick?: (item?: SidemenuItemV2Props) => void
+  /** On collapse callback */
+  onCollapse?: (item?: SidemenuItemV2Props) => void
+  /** On expand callback */
+  onExpand?: (item?: SidemenuItemV2Props) => void
+  /** Router path */
+  path?: string
+  /** Display title */
+  title: string
+  /** Subtitle or description */
+  subtitle?: string
+  /** Tooltip content (shown when collapsed) */
+  tooltip?: string | ReactNode
+  /** Badge configuration */
+  badge?: Pick<BadgeProps, 'text' | 'variant'>
+  badgeLinkUrl?: string
+  /** Keyboard shortcut display */
+  shortcut?: string
+  /** Item visibility @default true */
+  visible?: boolean
+  /** Item priority for sorting @default 0 */
+  priority?: number
+  /** Nesting level (auto-calculated if not provided) */
+  level?: number
+  /** External link indicator @default false */
+  isExternal?: boolean
+  /** Target for external links @default '_blank' */
+  target?: string
+  /** Whether item is new (shows indicator) @default false */
+  isNew?: boolean
+  /** Whether item is beta (shows indicator) @default false */
+  isBeta?: boolean
+  /** Custom status text */
+  status?: string
+  /** Item category for grouping */
+  category?: string
+  /** ARIA label override */
+  'aria-label'?: string
+  /** ARIA description */
+  'aria-describedby'?: string
+  /** Test ID for this specific item */
+  'data-testid'?: string
+  /** Custom component to render as */
+  as?: React.ElementType
+  /** Before icon slot */
+  beforeIcon?: ReactNode
+  /** After icon slot */
+  afterIcon?: ReactNode
+  /** Custom metadata */
+  meta?: Record<string, any>
+  /** Whether item is positioned at bottom @default false */
+  onBottom?: boolean
+}
+
+export type SidemenuTopV2Props = BoxProps & {
+  /** Custom class name */
+  className?: string
+  /** Left slot (always visible) */
+  leftSlot?: ReactNode
+  /** Right slot (hidden when collapsed) */
+  rightSlot?: ReactNode
+  /** Center slot for title/branding */
+  centerSlot?: ReactNode
+  /** Whether to show collapse toggle @default true */
+  showCollapseToggle?: boolean
+  /** Custom collapse toggle component */
+  CollapseToggle?: React.ComponentType<{
+    isExpanded: boolean
+    onClick: () => void
+    disabled?: boolean
+  }>
+  /** Collapse toggle position @default 'right' */
+  collapseTogglePosition?: 'left' | 'right' | 'center'
+  /** Top section height @default 'auto' */
+  height?: string | number
+  /** Sticky behavior @default false */
+  isSticky?: boolean
+  /** Background variant */
+  background?: 'transparent' | 'default' | 'brand'
+  /** Border configuration */
+  border?: 'none' | 'bottom' | 'full'
+  /** Custom actions */
+  actions?: ReactNode
+  /** Test ID */
+  'data-testid'?: string
+  /** Disabled state @default false */
+  disabled?: boolean
+  /** Loading state @default false */
+  isLoading?: boolean
+  /** Error state */
+  error?: string | ReactNode
+}
+
+export type SidemenuGroupV2Props = {
+  /** Group title */
+  title?: string
+  /** Group items */
+  items: SidemenuItemV2Props[]
+  /** Whether group is collapsible @default true */
+  collapsible?: boolean
+  /** Whether group is expanded by default @default true */
+  defaultExpanded?: boolean
+  /** Group icon */
+  icon?: IconProp
+  /** Group priority for ordering @default 0 */
+  priority?: number
+  /** Group visibility @default true */
+  visible?: boolean
+  /** Group category */
+  category?: string
+  /** Divider after group @default false */
+  showDivider?: boolean
+  /** Custom group header renderer */
+  renderHeader?: (props: SidemenuGroupV2Props) => ReactNode
+  /** Test ID for group */
+  'data-testid'?: string
+}
+
+export type SidemenuContextV2Value = {
+  /** Current expansion state */
+  isExpanded: boolean
+  /** Toggle expansion */
+  toggleExpanded: () => void
+  /** Current size */
+  size: SidemenuSizeV2
+  /** Current variant */
+  variant: SidemenuVariantV2
+  /** Navigation function */
+  navigate: (to: string, item?: SidemenuItemV2Props) => void
+  /** Active item path */
+  activePath?: string
+  /** Set active item */
+  setActivePath: (path: string) => void
+  /** Disabled state */
+  disabled?: boolean
+  /** Loading state */
+  isLoading?: boolean
+  /** Theme context */
+  isDark?: boolean
+  /** Width values */
+  width: number
+  collapsedWidth: number
+  /** Animation settings */
+  animationDuration: number
+  disableAnimation: boolean
+}
+
+// Hook return types
+export type UseSidemenuV2Return = {
+  /** Expansion state */
+  isExpanded: boolean
+  /** Toggle function */
+  toggle: () => void
+  /** Expand function */
+  expand: () => void
+  /** Collapse function */
+  collapse: () => void
+  /** Navigation function */
+  navigate: (to: string) => void
+  /** Active item */
+  activeItem?: SidemenuItemV2Props
+  /** Set active item */
+  setActiveItem: (item: SidemenuItemV2Props) => void
+  /** Context value */
+  contextValue: SidemenuContextV2Value
+}
+
+export type UseSidemenuItemV2Return = {
+  /** Item expansion state */
+  isExpandedVertically: boolean
+  /** Toggle vertical expansion */
+  setIsExpandedVertically: (expanded: boolean) => void
+  /** Theme detection */
+  isDark: boolean
+  /** Size from context */
+  size: SidemenuSizeV2
+  /** Horizontal expansion from sidemenu */
+  isExpandedHorizontally: boolean
+  /** Computed styles */
+  styles: Record<string, any>
+  /** Item ref */
+  itemRef: React.RefObject<HTMLElement>
+  /** Focus management */
+  focus: () => void
+  /** Blur management */
+  blur: () => void
+  /** Active state */
+  isActive: boolean
+  /** Disabled state */
+  disabled: boolean
+}
+
+// Event types
+export type SidemenuItemClickEventV2 = {
+  item: SidemenuItemV2Props
+  path?: string
+  preventDefault: () => void
+  isDefaultPrevented: boolean
+}
+
+export type SidemenuExpandEventV2 = {
+  isExpanded: boolean
+  width: number
+  duration: number
+}
+
+// Utility types
+export type SidemenuItemWithChildrenV2 = SidemenuItemV2Props & {
+  children: SidemenuItemV2Props[]
+}
+
+export type SidemenuFlatItemV2 = SidemenuItemV2Props & {
+  level: number
+  parentPath?: string
+  fullPath: string
+}
+
+// Component prop types for strict typing
+export type SidemenuComponentV2Props = ComponentProps<'nav'> & SidemenuV2Props
+export type SidemenuItemComponentV2Props = ComponentProps<'button'> & SidemenuItemV2Props
+export type SidemenuTopComponentV2Props = ComponentProps<'div'> & SidemenuTopV2Props