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

package/src/ui/molecules/SidebarGroup/SidebarGroup.stories.tsx

@@ -0,0 +1,173 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import SidebarGroup from "./SidebarGroup";
+import SidebarItem from "../../atoms/SidebarItem/SidebarItem";
+
+const meta: Meta<typeof SidebarGroup> = {
+  title: "UI/Molecules/SidebarGroup",
+  component: SidebarGroup,
+  parameters: {
+    docs: {
+      description: {
+        component: "A group container for sidebar items with optional title. Supports collapsible groups.",
+      },
+    },
+  },
+  argTypes: {
+    title: {
+      control: "text",
+      description: "Title text for the group",
+    },
+    collapsible: {
+      control: "boolean",
+      description: "Whether the group can be collapsed",
+    },
+    defaultCollapsed: {
+      control: "boolean",
+      description: "Initial collapsed state (uncontrolled mode)",
+    },
+  },
+};
+
+export const Default: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Agile",
+    children: (
+      <>
+        <SidebarItem href="/epics">Epics</SidebarItem>
+        <SidebarItem href="/stories">Stories</SidebarItem>
+        <SidebarItem href="/tasks">Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const WithoutTitle: StoryObj<typeof SidebarGroup> = {
+  args: {
+    children: (
+      <>
+        <SidebarItem href="/kanban">Kanban</SidebarItem>
+        <SidebarItem href="/sprints">Sprints</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const Collapsible: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: false,
+    children: (
+      <>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const CollapsibleDefaultCollapsed: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: true,
+    children: (
+      <>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const ControlledCollapsible: StoryObj<typeof SidebarGroup> = {
+  render: () => {
+    const [collapsed, setCollapsed] = useState(false);
+    return (
+      <div className="space-y-4">
+        <button
+          onClick={() => setCollapsed(!collapsed)}
+          className="px-4 py-2 bg-gray-100 rounded"
+        >
+          {collapsed ? "Expand" : "Collapse"} (External Control)
+        </button>
+        <SidebarGroup
+          title="Backlog"
+          collapsible={true}
+          collapsed={collapsed}
+          onCollapseChange={setCollapsed}
+        >
+          <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+          <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+          <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+        </SidebarGroup>
+      </div>
+    );
+  },
+};
+
+export const WithNestedItems: StoryObj<typeof SidebarGroup> = {
+  args: {
+    title: "Backlog",
+    collapsible: true,
+    defaultCollapsed: false,
+    children: (
+      <>
+        <SidebarItem
+          href="/epics"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+          }
+        >
+          Epics
+        </SidebarItem>
+        <SidebarItem
+          href="/stories"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+          }
+        >
+          Stories
+        </SidebarItem>
+        <SidebarItem
+          href="/tasks"
+          nested={true}
+          icon={
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+            </svg>
+          }
+        >
+          Tasks
+        </SidebarItem>
+      </>
+    ),
+  },
+};
+
+export const MultipleGroups: StoryObj<typeof SidebarGroup> = {
+  render: () => (
+    <div className="w-64 bg-white border-r border-gray-200 p-4 space-y-4">
+      <SidebarGroup title="Backlog" collapsible={true} defaultCollapsed={false}>
+        <SidebarItem href="/epics" nested={true}>Epics</SidebarItem>
+        <SidebarItem href="/stories" nested={true}>Stories</SidebarItem>
+        <SidebarItem href="/tasks" nested={true}>Tasks</SidebarItem>
+      </SidebarGroup>
+      <SidebarGroup>
+        <SidebarItem href="/kanban">Kanban</SidebarItem>
+        <SidebarItem href="/sprints">Sprints</SidebarItem>
+      </SidebarGroup>
+    </div>
+  ),
+};
+
+export default meta;

package/src/ui/molecules/SidebarGroup/SidebarGroup.test.tsx

@@ -0,0 +1,131 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import SidebarGroup from './SidebarGroup';
+import SidebarItem from '../../atoms/SidebarItem/SidebarItem';
+
+describe('SidebarGroup', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  it('renders title and children', () => {
+    render(
+      <SidebarGroup title="Test Group">
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    expect(screen.getByText('Test Group')).toBeInTheDocument();
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+  });
+
+  it('renders without title', () => {
+    render(
+      <SidebarGroup>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+  });
+
+  it('collapses and expands when collapsible', async () => {
+    render(
+      <SidebarGroup title="Collapsible Group" collapsible={true} defaultCollapsed={false}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Collapsible Group').closest('button');
+    expect(title).toBeInTheDocument();
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+
+    fireEvent.click(title!);
+
+    await waitFor(() => {
+      const item = screen.queryByText('Test Item');
+      // Item should be hidden (aria-hidden="true")
+      expect(item?.parentElement?.parentElement).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+
+  it('starts collapsed when defaultCollapsed is true', () => {
+    render(
+      <SidebarGroup title="Collapsible Group" collapsible={true} defaultCollapsed={true}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const content = screen.getByText('Test Item').parentElement?.parentElement;
+    expect(content).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('calls onCollapseChange when provided (controlled mode)', () => {
+    const handleCollapseChange = vi.fn();
+    render(
+      <SidebarGroup
+        title="Controlled Group"
+        collapsible={true}
+        collapsed={false}
+        onCollapseChange={handleCollapseChange}
+      >
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Controlled Group').closest('button');
+    fireEvent.click(title!);
+
+    expect(handleCollapseChange).toHaveBeenCalledWith(true);
+  });
+
+  it('persists state in localStorage when storageKey is provided', async () => {
+    const storageKey = 'test-sidebar-group';
+    
+    render(
+      <SidebarGroup
+        title="Persistent Group"
+        collapsible={true}
+        defaultCollapsed={false}
+        storageKey={storageKey}
+      >
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Persistent Group').closest('button');
+    fireEvent.click(title!);
+
+    await waitFor(() => {
+      expect(localStorage.getItem(storageKey)).toBe('false');
+    });
+  });
+
+  it('shows chevron icon when collapsible and showChevron is true', () => {
+    render(
+      <SidebarGroup title="Group" collapsible={true} showChevron={true}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Group').closest('button');
+    const svg = title?.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+  });
+
+  it('hides chevron icon when showChevron is false', () => {
+    render(
+      <SidebarGroup title="Group" collapsible={true} showChevron={false}>
+        <SidebarItem href="/test">Test Item</SidebarItem>
+      </SidebarGroup>
+    );
+
+    const title = screen.getByText('Group').closest('button');
+    const svg = title?.querySelector('svg');
+    expect(svg).not.toBeInTheDocument();
+  });
+});

package/src/ui/molecules/SidebarGroup/SidebarGroup.tsx

@@ -1,11 +1,21 @@
 'use client';
 
 import type { HTMLAttributes, ReactNode } from "react";
+import { ChevronRight } from "lucide-react";
 import { Text } from "../../atoms";
+import Collapsible from "../../atoms/Collapsible/Collapsible";
+import { SIDEBAR_TOKENS } from "../../tokens/sidebar";
 
 export interface SidebarGroupProps extends HTMLAttributes<HTMLDivElement> {
   title?: string;
+  titleIcon?: ReactNode; // Optional icon for the title
   children: ReactNode;
+  collapsible?: boolean;
+  defaultCollapsed?: boolean;
+  collapsed?: boolean; // Controlled mode
+  onCollapseChange?: (collapsed: boolean) => void;
+  storageKey?: string; // For localStorage persistence
+  showChevron?: boolean; // Default: true when collapsible
 }
 
 /**
@@ -24,29 +34,86 @@ export interface SidebarGroupProps extends HTMLAttributes<HTMLDivElement> {
  */
 export default function SidebarGroup({
   title,
+  titleIcon,
   children,
+  collapsible = false,
+  defaultCollapsed = false,
+  collapsed,
+  onCollapseChange,
+  storageKey,
+  showChevron = true,
   className = "",
   ...props
 }: SidebarGroupProps) {
-  const baseClasses = [
-    "space-y-1",
-  ];
+  const baseClasses = ["space-y-1"];
+  const classes = [...baseClasses, className].filter(Boolean).join(" ");
 
-  const classes = [
-    ...baseClasses,
-    className,
-  ].filter(Boolean).join(" ");
+  // Chevron icon component using lucide-react
+  const ChevronIcon = ({ isOpen }: { isOpen: boolean }) => (
+    <ChevronRight
+      className={`${SIDEBAR_TOKENS.chevron.size} ${SIDEBAR_TOKENS.chevron.color} transition-transform duration-200 ${
+        isOpen ? 'rotate-90' : ''
+      }`}
+    />
+  );
+
+  // If collapsible and has title, use Collapsible component
+  if (collapsible && title) {
+    return (
+      <Collapsible
+        defaultOpen={!defaultCollapsed}
+        open={collapsed !== undefined ? !collapsed : undefined}
+        onOpenChange={(open) => onCollapseChange?.(!open)}
+        storageKey={storageKey}
+        trigger={
+          <div className={`${SIDEBAR_TOKENS.spacing.groupTitlePadding} flex items-center justify-between w-full hover:bg-gray-50 rounded-md transition-colors cursor-pointer`}>
+            <div className="flex items-center gap-2">
+              {titleIcon && (
+                <span className={`${SIDEBAR_TOKENS.icon.md} ${SIDEBAR_TOKENS.colors.groupTitle}`}>
+                  {titleIcon}
+                </span>
+              )}
+              <Text
+                as="h3"
+                className={`${SIDEBAR_TOKENS.text.xs} font-semibold ${SIDEBAR_TOKENS.colors.groupTitle} uppercase tracking-wider`}
+              >
+                {title}
+              </Text>
+            </div>
+            {showChevron && (
+              <span className="ml-2">
+                <ChevronIcon isOpen={collapsed !== undefined ? !collapsed : !defaultCollapsed} />
+              </span>
+            )}
+          </div>
+        }
+        className={classes}
+        {...props}
+      >
+        <div className="space-y-1">{children}</div>
+      </Collapsible>
+    );
+  }
 
+  // Non-collapsible group (default behavior)
   return (
     <div className={classes} {...props}>
       {title && (
-        <Text as="h3" className="px-4 py-2 text-xs font-semibold text-gray-500 uppercase tracking-wider">
-          {title}
-        </Text>
+        <div className={`${SIDEBAR_TOKENS.spacing.groupTitlePadding} flex items-center gap-2`}>
+          {titleIcon && (
+            <span className={`${SIDEBAR_TOKENS.icon.md} ${SIDEBAR_TOKENS.colors.groupTitle}`}>
+              {titleIcon}
+            </span>
+          )}
+          <Text
+            as="h3"
+            className={`${SIDEBAR_TOKENS.text.xs} font-semibold ${SIDEBAR_TOKENS.colors.groupTitle} uppercase tracking-wider`}
+          >
+            {title}
+          </Text>
+        </div>
       )}
-      <div className="space-y-1">
-        {children}
-      </div>
+      <div className="space-y-1">{children}</div>
     </div>
   );
 }

package/src/ui/providers/ThemeProvider.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
+import { COLOR_TOKENS_LIGHT, COLOR_TOKENS_DARK, type ColorRole, type SemanticColor } from '../tokens/colors';
+import type { ThemeMode } from '../tokens/tokens.factory';
+
+export interface ThemeContextValue {
+  theme: ThemeMode;
+  toggleTheme: () => void;
+  setTheme: (theme: ThemeMode) => void;
+  colors: Record<ColorRole, SemanticColor>;
+  isDark: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  defaultTheme?: ThemeMode;
+  storageKey?: string;
+}
+
+/**
+ * ThemeProvider Component
+ * 
+ * Provides theme context to the application.
+ * Uses Strategy Pattern for different theme strategies (light, dark).
+ * Uses Observer Pattern to notify components about theme changes.
+ * 
+ * @example
+ * ```tsx
+ * <ThemeProvider defaultTheme="light">
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+  children,
+  defaultTheme = 'light',
+  storageKey = 'theme',
+}: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<ThemeMode>(() => {
+    if (typeof window === 'undefined') {
+      return defaultTheme;
+    }
+
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored === 'light' || stored === 'dark') {
+        return stored;
+      }
+    } catch (error) {
+      console.warn('Failed to read theme from localStorage:', error);
+    }
+
+    return defaultTheme;
+  });
+
+  useEffect(() => {
+    try {
+      localStorage.setItem(storageKey, theme);
+    } catch (error) {
+      console.warn('Failed to save theme to localStorage:', error);
+    }
+
+    // Apply theme class to document root
+    document.documentElement.classList.remove('light', 'dark');
+    document.documentElement.classList.add(theme);
+  }, [theme, storageKey]);
+
+  const toggleTheme = () => {
+    setThemeState((prev) => (prev === 'light' ? 'dark' : 'light'));
+  };
+
+  const setTheme = (newTheme: ThemeMode) => {
+    setThemeState(newTheme);
+  };
+
+  const colors = theme === 'light' ? COLOR_TOKENS_LIGHT : COLOR_TOKENS_DARK;
+
+  const value: ThemeContextValue = {
+    theme,
+    toggleTheme,
+    setTheme,
+    colors,
+    isDark: theme === 'dark',
+  };
+
+  return (
+    <ThemeContext.Provider value={value}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+/**
+ * Hook to use theme context
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}

package/src/ui/tokens/breakpoints.ts

@@ -0,0 +1,71 @@
+/**
+ * Breakpoint Tokens
+ * 
+ * Responsive breakpoints for consistent media queries.
+ * Uses Factory Pattern for type-safe breakpoint creation.
+ */
+
+export type BreakpointName = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export interface BreakpointToken {
+  name: BreakpointName;
+  minWidth: number;
+  px: string;
+  rem: string;
+  tailwind: string;
+}
+
+/**
+ * Breakpoint Token Factory
+ * Creates breakpoint tokens with consistent values
+ */
+export class BreakpointTokenFactory {
+  /**
+   * Create breakpoint token
+   */
+  static create(name: BreakpointName): BreakpointToken {
+    const breakpointMap: Record<BreakpointName, { minWidth: number; tailwind: string }> = {
+      sm: { minWidth: 640, tailwind: 'sm' },
+      md: { minWidth: 768, tailwind: 'md' },
+      lg: { minWidth: 1024, tailwind: 'lg' },
+      xl: { minWidth: 1280, tailwind: 'xl' },
+      '2xl': { minWidth: 1536, tailwind: '2xl' },
+    };
+
+    const config = breakpointMap[name];
+    return {
+      name,
+      minWidth: config.minWidth,
+      px: `${config.minWidth}px`,
+      rem: `${config.minWidth / 16}rem`,
+      tailwind: config.tailwind,
+    };
+  }
+}
+
+/**
+ * Pre-defined breakpoint tokens
+ */
+export const BREAKPOINT_TOKENS: Record<BreakpointName, BreakpointToken> = {
+  sm: BreakpointTokenFactory.create('sm'),
+  md: BreakpointTokenFactory.create('md'),
+  lg: BreakpointTokenFactory.create('lg'),
+  xl: BreakpointTokenFactory.create('xl'),
+  '2xl': BreakpointTokenFactory.create('2xl'),
+} as const;
+
+/**
+ * Helper function to get breakpoint token
+ */
+export function getBreakpoint(name: BreakpointName): BreakpointToken {
+  return BREAKPOINT_TOKENS[name];
+}
+
+/**
+ * Helper function to create media query string
+ */
+export function getMediaQuery(name: BreakpointName, direction: 'min' | 'max' = 'min'): string {
+  const breakpoint = BREAKPOINT_TOKENS[name];
+  const operator = direction === 'min' ? 'min-width' : 'max-width';
+  return `@media (${operator}: ${breakpoint.px})`;
+}