@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/organisms/SideNavbar/hooks/useGroupState.ts

@@ -0,0 +1,86 @@
+'use client';
+
+import { useState, useCallback, useEffect } from 'react';
+import type { UseGroupStateOptions, UseGroupStateReturn } from '../types';
+
+/**
+ * Hook for managing collapsible group states
+ *
+ * Manages collapsed/expanded state for multiple groups with optional persistence.
+ * Used internally by SideNavbarStateProvider, but can be used standalone.
+ *
+ * @example
+ * ```tsx
+ * const { groupStates, toggleGroup, setGroupCollapsed } = useGroupState({
+ *   defaultStates: { filters: false, settings: true },
+ *   persist: true,
+ *   storageKey: 'my-sidebar-groups',
+ * });
+ *
+ * // Check if group is collapsed
+ * const isFiltersCollapsed = groupStates['filters'] ?? false;
+ *
+ * // Toggle a group
+ * toggleGroup('filters');
+ *
+ * // Set specific state
+ * setGroupCollapsed('settings', false);
+ * ```
+ */
+export function useGroupState({
+  defaultStates = {},
+  persist = false,
+  storageKey,
+}: UseGroupStateOptions = {}): UseGroupStateReturn {
+  // Initialize state from storage or defaults
+  const getInitialStates = (): Record<string, boolean> => {
+    if (persist && storageKey && typeof window !== 'undefined') {
+      const stored = localStorage.getItem(`${storageKey}-groups`);
+      if (stored) {
+        try {
+          const parsed = JSON.parse(stored);
+          return { ...defaultStates, ...parsed };
+        } catch {
+          // Invalid JSON, use defaults
+        }
+      }
+    }
+    return defaultStates;
+  };
+
+  const [groupStates, setGroupStates] = useState<Record<string, boolean>>(getInitialStates);
+
+  // Persist state changes
+  useEffect(() => {
+    if (persist && storageKey && typeof window !== 'undefined') {
+      localStorage.setItem(`${storageKey}-groups`, JSON.stringify(groupStates));
+    }
+  }, [persist, storageKey, groupStates]);
+
+  const toggleGroup = useCallback((groupId: string) => {
+    setGroupStates((prev) => ({
+      ...prev,
+      [groupId]: !prev[groupId],
+    }));
+  }, []);
+
+  const setGroupCollapsed = useCallback((groupId: string, collapsed: boolean) => {
+    setGroupStates((prev) => ({
+      ...prev,
+      [groupId]: collapsed,
+    }));
+  }, []);
+
+  const resetGroups = useCallback(() => {
+    setGroupStates(defaultStates);
+  }, [defaultStates]);
+
+  return {
+    groupStates,
+    toggleGroup,
+    setGroupCollapsed,
+    resetGroups,
+  };
+}
+
+export default useGroupState;

package/src/ui/organisms/SideNavbar/hooks/useKeyboardShortcut.ts

@@ -0,0 +1,130 @@
+'use client';
+
+import { useEffect, useCallback } from 'react';
+
+export interface UseKeyboardShortcutOptions {
+  /**
+   * Key to listen for (e.g., 'b', 'Escape', 'Enter')
+   */
+  key: string;
+
+  /**
+   * Whether Ctrl/Cmd key should be pressed
+   * @default false
+   */
+  ctrl?: boolean;
+
+  /**
+   * Whether Shift key should be pressed
+   * @default false
+   */
+  shift?: boolean;
+
+  /**
+   * Whether Alt key should be pressed
+   * @default false
+   */
+  alt?: boolean;
+
+  /**
+   * Whether Meta key should be pressed (Cmd on Mac)
+   * @default false
+   */
+  meta?: boolean;
+
+  /**
+   * Callback when shortcut is triggered
+   */
+  onTrigger: () => void;
+
+  /**
+   * Whether the shortcut is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Whether to prevent default behavior
+   * @default true
+   */
+  preventDefault?: boolean;
+}
+
+/**
+ * Hook for keyboard shortcuts
+ *
+ * Listens for keyboard combinations and triggers callbacks.
+ * Automatically ignores input fields unless explicitly allowed.
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcut({
+ *   key: 'b',
+ *   ctrl: true,
+ *   onTrigger: () => toggleSidebar(),
+ * });
+ * ```
+ */
+export function useKeyboardShortcut({
+  key: targetKey,
+  ctrl = false,
+  shift = false,
+  alt = false,
+  meta = false,
+  onTrigger,
+  enabled = true,
+  preventDefault = true,
+}: UseKeyboardShortcutOptions) {
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!enabled) return;
+
+      // Don't trigger in input fields (unless it's a system shortcut)
+      const target = event.target as HTMLElement;
+      const isInputField =
+        target.tagName === 'INPUT' ||
+        target.tagName === 'TEXTAREA' ||
+        target.isContentEditable;
+
+      // Allow Ctrl/Cmd shortcuts in inputs (like Ctrl+B)
+      if (isInputField && !ctrl && !meta) {
+        return;
+      }
+
+      // Check key match (case-insensitive for letter keys)
+      const keyMatch =
+        targetKey.length === 1
+          ? event.key.toLowerCase() === targetKey.toLowerCase()
+          : event.key === targetKey;
+
+      // Check modifier keys
+      const ctrlMatch = ctrl ? event.ctrlKey || event.metaKey : !event.ctrlKey && !event.metaKey;
+      const shiftMatch = shift ? event.shiftKey : !event.shiftKey;
+      const altMatch = alt ? event.altKey : !event.altKey;
+      const metaMatch = meta ? event.metaKey : !event.metaKey;
+
+      // If ctrl is true, allow either Ctrl or Meta (Cmd on Mac)
+      const modifierMatch = ctrl
+        ? (event.ctrlKey || event.metaKey) && !meta
+        : ctrlMatch && metaMatch;
+
+      if (keyMatch && modifierMatch && shiftMatch && altMatch) {
+        if (preventDefault) {
+          event.preventDefault();
+          event.stopPropagation();
+        }
+        onTrigger();
+      }
+    },
+    [enabled, targetKey, ctrl, shift, alt, meta, onTrigger, preventDefault]
+  );
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [enabled, handleKeyDown]);
+}

package/src/ui/organisms/SideNavbar/hooks/useNavbar.ts

@@ -0,0 +1,17 @@
+'use client';
+
+/**
+ * Hook to access Navbar context
+ * 
+ * Re-exports the hooks from NavbarContext for convenience.
+ * Use this hook to access navbar-specific state within Navbar subcomponents.
+ * 
+ * @example
+ * ```tsx
+ * function NavbarItem() {
+ *   const { activeItem, setActiveItem, collapsed } = useNavbar();
+ *   // ...
+ * }
+ * ```
+ */
+export { useNavbar, useNavbarRequired } from '../contexts/NavbarContext';

package/src/ui/organisms/SideNavbar/hooks/useResize.ts

@@ -0,0 +1,198 @@
+'use client';
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { clampWidth, validateWidthBounds } from '../utils';
+
+export interface UseResizeOptions {
+  /**
+   * Initial width
+   */
+  initialWidth: number;
+
+  /**
+   * Minimum width constraint
+   */
+  minWidth?: number;
+
+  /**
+   * Maximum width constraint
+   */
+  maxWidth?: number;
+
+  /**
+   * Snap points (widths to snap to when dragging)
+   */
+  snapPoints?: number[];
+
+  /**
+   * Snap threshold in pixels
+   * @default 20
+   */
+  snapThreshold?: number;
+
+  /**
+   * Callback when width changes
+   */
+  onWidthChange?: (width: number) => void;
+
+  /**
+   * Whether resize is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+export interface UseResizeReturn {
+  /**
+   * Current width
+   */
+  width: number;
+
+  /**
+   * Whether currently resizing
+   */
+  isResizing: boolean;
+
+  /**
+   * Start resize handler (attach to mousedown)
+   */
+  startResize: (event: React.MouseEvent) => void;
+
+  /**
+   * Set width programmatically
+   */
+  setWidth: (width: number) => void;
+}
+
+/**
+ * Hook for drag-to-resize functionality
+ *
+ * Provides resize state and handlers for drag-to-resize interactions.
+ * Supports snap points and min/max constraints.
+ *
+ * @example
+ * ```tsx
+ * const { width, isResizing, startResize } = useResize({
+ *   initialWidth: 320,
+ *   minWidth: 200,
+ *   maxWidth: 600,
+ *   snapPoints: [200, 320, 480],
+ *   onWidthChange: (width) => console.log('Width:', width)
+ * });
+ * ```
+ */
+export function useResize({
+  initialWidth,
+  minWidth,
+  maxWidth,
+  snapPoints,
+  snapThreshold = 20,
+  onWidthChange,
+  enabled = true,
+}: UseResizeOptions): UseResizeReturn {
+  // Validate bounds on first render
+  if (process.env.NODE_ENV === 'development') {
+    if (!validateWidthBounds(minWidth, maxWidth)) {
+      console.warn(
+        '[useResize] Invalid bounds: minWidth must be less than maxWidth',
+        { minWidth, maxWidth }
+      );
+    }
+  }
+
+  // Clamp initial width to valid bounds
+  const clampedInitialWidth = clampWidth(initialWidth, minWidth, maxWidth);
+  const [width, setWidthState] = useState(clampedInitialWidth);
+  const [isResizing, setIsResizing] = useState(false);
+  const startXRef = useRef<number>(0);
+  const startWidthRef = useRef<number>(clampedInitialWidth);
+
+  const setWidth = useCallback(
+    (newWidth: number) => {
+      // Use utility function to clamp width
+      let constrainedWidth = clampWidth(newWidth, minWidth, maxWidth);
+
+      // Check snap points
+      if (snapPoints && snapPoints.length > 0) {
+        const closestSnap = snapPoints.reduce((closest, snap) => {
+          const distanceToSnap = Math.abs(constrainedWidth - snap);
+          const distanceToClosest = Math.abs(constrainedWidth - closest);
+          return distanceToSnap < distanceToClosest ? snap : closest;
+        }, snapPoints[0]);
+
+        if (Math.abs(constrainedWidth - closestSnap) <= snapThreshold) {
+          constrainedWidth = closestSnap;
+        }
+      }
+
+      setWidthState(constrainedWidth);
+      onWidthChange?.(constrainedWidth);
+    },
+    [minWidth, maxWidth, snapPoints, snapThreshold, onWidthChange]
+  );
+
+  const handleMouseMove = useCallback(
+    (event: MouseEvent) => {
+      if (!enabled || !isResizing) return;
+
+      const deltaX = event.clientX - startXRef.current;
+      const newWidth = startWidthRef.current + deltaX;
+      setWidth(newWidth);
+    },
+    [enabled, isResizing, setWidth]
+  );
+
+  const handleMouseUp = useCallback(() => {
+    if (!enabled) return;
+
+    setIsResizing(false);
+    startXRef.current = 0;
+    startWidthRef.current = width;
+  }, [enabled, width]);
+
+  const startResize = useCallback(
+    (event: React.MouseEvent) => {
+      if (!enabled) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      setIsResizing(true);
+      startXRef.current = event.clientX;
+      startWidthRef.current = width;
+    },
+    [enabled, width]
+  );
+
+  useEffect(() => {
+    if (!isResizing) return;
+
+    document.addEventListener('mousemove', handleMouseMove);
+    document.addEventListener('mouseup', handleMouseUp);
+
+    // Prevent text selection while resizing
+    document.body.style.userSelect = 'none';
+    document.body.style.cursor = 'col-resize';
+
+    return () => {
+      document.removeEventListener('mousemove', handleMouseMove);
+      document.removeEventListener('mouseup', handleMouseUp);
+      document.body.style.userSelect = '';
+      document.body.style.cursor = '';
+    };
+  }, [isResizing, handleMouseMove, handleMouseUp]);
+
+  // Update width when initialWidth changes externally
+  useEffect(() => {
+    if (!isResizing) {
+      setWidthState(clampWidth(initialWidth, minWidth, maxWidth));
+    }
+  }, [initialWidth, minWidth, maxWidth, isResizing]);
+
+  return {
+    width,
+    isResizing,
+    startResize,
+    setWidth,
+  };
+}

package/src/ui/organisms/SideNavbar/hooks/useResponsiveSidebar.ts

@@ -0,0 +1,106 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+
+export interface UseResponsiveSidebarOptions {
+  /**
+   * Breakpoint in pixels for mobile detection
+   * @default 768
+   */
+  mobileBreakpoint?: number;
+
+  /**
+   * Callback when mobile state changes
+   */
+  onMobileChange?: (isMobile: boolean) => void;
+
+  /**
+   * Whether responsive behavior is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+export interface UseResponsiveSidebarReturn {
+  /**
+   * Whether current viewport is mobile
+   */
+  isMobile: boolean;
+
+  /**
+   * Current viewport width
+   */
+  viewportWidth: number;
+}
+
+/**
+ * Hook for responsive sidebar behavior
+ *
+ * Detects mobile breakpoints and provides responsive state.
+ *
+ * @example
+ * ```tsx
+ * const { isMobile, viewportWidth } = useResponsiveSidebar({
+ *   mobileBreakpoint: 768,
+ *   onMobileChange: (isMobile) => console.log('Mobile:', isMobile)
+ * });
+ * ```
+ */
+export function useResponsiveSidebar({
+  mobileBreakpoint = 768,
+  onMobileChange,
+  enabled = true,
+}: UseResponsiveSidebarOptions = {}): UseResponsiveSidebarReturn {
+  const [viewportWidth, setViewportWidth] = useState<number>(
+    typeof window !== 'undefined' ? window.innerWidth : 1024
+  );
+  const [isMobile, setIsMobile] = useState<boolean>(
+    typeof window !== 'undefined' ? window.innerWidth < mobileBreakpoint : false
+  );
+
+  const handleResize = useCallback(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    const newWidth = window.innerWidth;
+    const newIsMobile = newWidth < mobileBreakpoint;
+
+    setViewportWidth(newWidth);
+
+    if (newIsMobile !== isMobile) {
+      setIsMobile(newIsMobile);
+      onMobileChange?.(newIsMobile);
+    }
+  }, [enabled, mobileBreakpoint, isMobile, onMobileChange]);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    // Set initial state
+    const initialWidth = window.innerWidth;
+    const initialIsMobile = initialWidth < mobileBreakpoint;
+    setViewportWidth(initialWidth);
+    setIsMobile(initialIsMobile);
+
+    // Listen for resize events
+    window.addEventListener('resize', handleResize);
+
+    // Use ResizeObserver for more accurate detection
+    let resizeObserver: ResizeObserver | null = null;
+    if (window.ResizeObserver) {
+      resizeObserver = new ResizeObserver(() => {
+        handleResize();
+      });
+      resizeObserver.observe(document.body);
+    }
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      resizeObserver?.disconnect();
+    };
+  }, [enabled, mobileBreakpoint, handleResize]);
+
+  return {
+    isMobile,
+    viewportWidth,
+  };
+}

package/src/ui/organisms/SideNavbar/hooks/useSideNavbar.ts

@@ -0,0 +1,63 @@
+'use client';
+
+// Layered context hooks
+export {
+  useSideNavbarTheme,
+  useSideNavbarThemeRequired,
+} from '../contexts/SideNavbarThemeContext';
+
+export {
+  useSideNavbarConfig,
+  useSideNavbarConfigRequired,
+} from '../contexts/SideNavbarConfigContext';
+
+export {
+  useSideNavbarState,
+  useSideNavbarStateRequired,
+} from '../contexts/SideNavbarStateContext';
+
+// Subcomponent hooks
+export { useNavbar, useNavbarRequired } from './useNavbar';
+export { useSidebar, useSidebarRequired } from './useSidebar';
+
+// Utility hooks
+export { useResize } from './useResize';
+export type { UseResizeOptions, UseResizeReturn } from './useResize';
+
+export { useResponsiveSidebar } from './useResponsiveSidebar';
+export type { UseResponsiveSidebarOptions, UseResponsiveSidebarReturn } from './useResponsiveSidebar';
+
+export { useKeyboardShortcut } from './useKeyboardShortcut';
+export type { UseKeyboardShortcutOptions } from './useKeyboardShortcut';
+
+export { useFocusManagement } from './useFocusManagement';
+export type { UseFocusManagementOptions } from './useFocusManagement';
+
+export { useGroupState } from './useGroupState';
+export type { UseGroupStateOptions, UseGroupStateReturn } from '../types';
+
+// Navigation and content hooks
+export { useSideNavbarNavigation } from './useSideNavbarNavigation';
+export { useSideNavbarContent } from './useSideNavbarContent';
+
+/**
+ * Combined hook to access all root contexts
+ * 
+ * Returns an object with theme, config, and state contexts.
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { theme, config, state } = useSideNavbarCombined();
+ *   // Access theme.variant, config.mode, state.collapsed, etc.
+ * }
+ * ```
+ */
+export function useSideNavbarCombined() {
+  // Import here to avoid circular dependencies
+  const theme = useSideNavbarThemeRequired();
+  const config = useSideNavbarConfigRequired();
+  const state = useSideNavbarStateRequired();
+  
+  return { theme, config, state };
+}

package/src/ui/organisms/SideNavbar/hooks/useSideNavbarContent.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { useSidebarSlot } from '../contexts/SidebarSlotContext';
+import { useSidebar } from '../contexts/SidebarContext';
+
+/**
+ * Hook for content/slot management
+ *
+ * Provides access to sidebar slot state and scroll position.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { activeSlot, setActiveSlot, scrollPosition } = useSideNavbarContent();
+ *
+ *   return (
+ *     <div>
+ *       <p>Active slot: {activeSlot}</p>
+ *       <p>Scroll position: {scrollPosition}px</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSideNavbarContent() {
+  const slotContext = useSidebarSlot();
+  const sidebarContext = useSidebar();
+
+  return {
+    activeSlot: slotContext?.activeSlot ?? null,
+    setActiveSlot: slotContext?.setActiveSlot ?? (() => {}),
+    scrollPosition: sidebarContext?.scrollPosition ?? 0,
+    setScrollPosition: sidebarContext?.setScrollPosition ?? (() => {}),
+  };
+}

package/src/ui/organisms/SideNavbar/hooks/useSideNavbarNavigation.ts

@@ -0,0 +1,45 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useNavbarRequired } from '../contexts/NavbarContext';
+import { useSidebarSlot } from '../contexts/SidebarSlotContext';
+
+/**
+ * Hook for navigation-related state and actions
+ *
+ * Provides convenience methods for navigating between navbar items
+ * and managing associated sidebar slots.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { activeItem, navigate } = useSideNavbarNavigation();
+ *
+ *   return (
+ *     <button onClick={() => navigate('dashboard', 'dashboard-content')}>
+ *       Go to Dashboard
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useSideNavbarNavigation() {
+  const { activeItem, setActiveItem } = useNavbarRequired();
+  const slotContext = useSidebarSlot();
+
+  const navigate = useCallback(
+    (itemId: string, slotId?: string) => {
+      setActiveItem(itemId);
+      if (slotId && slotContext?.setActiveSlot) {
+        slotContext.setActiveSlot(slotId);
+      }
+    },
+    [setActiveItem, slotContext]
+  );
+
+  return {
+    activeItem,
+    setActiveItem,
+    navigate,
+  };
+}

package/src/ui/organisms/SideNavbar/hooks/useSidebar.ts

@@ -0,0 +1,17 @@
+'use client';
+
+/**
+ * Hook to access Sidebar context
+ * 
+ * Re-exports the hooks from SidebarContext for convenience.
+ * Use this hook to access sidebar-specific state within Sidebar subcomponents.
+ * 
+ * @example
+ * ```tsx
+ * function SidebarContent() {
+ *   const { collapsed, scrollPosition, setScrollPosition } = useSidebar();
+ *   // ...
+ * }
+ * ```
+ */
+export { useSidebar, useSidebarRequired } from '../contexts/SidebarContext';