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

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

@@ -0,0 +1,142 @@
+/**
+ * PageHeader Tests
+ * 
+ * Unit tests for the PageHeader component.
+ * Following TDD approach: tests first, then implementation.
+ * 
+ * @see EPIC-004: PageHeader Component (Molecule)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { PageHeader } from './PageHeader';
+import { Button } from '../../atoms/Button/Button';
+import type { BreadcrumbItem } from '../Breadcrumb/Breadcrumb';
+
+describe('PageHeader', () => {
+  describe('Rendering', () => {
+    it('should render with title', () => {
+      // TDD: Test basic rendering with title
+      render(<PageHeader title="Page Title" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+    });
+
+    it('should render with title and description', () => {
+      // TDD: Test rendering with description
+      render(<PageHeader title="Page Title" description="Page description" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+      expect(screen.getByText('Page description')).toBeInTheDocument();
+    });
+
+    it('should render with actions', () => {
+      // TDD: Test rendering with actions
+      render(
+        <PageHeader
+          title="Page Title"
+          actions={<Button>Action</Button>}
+        />
+      );
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+      expect(screen.getByText('Action')).toBeInTheDocument();
+    });
+  });
+
+  describe('Breadcrumb', () => {
+    it('should render breadcrumb when provided', () => {
+      // TDD: Test breadcrumb rendering
+      const breadcrumb: BreadcrumbItem[] = [
+        { label: 'Home', href: '/' },
+        { label: 'Page', href: '/page' },
+      ];
+
+      render(<PageHeader title="Page Title" breadcrumb={breadcrumb} />);
+      expect(screen.getByText('Home')).toBeInTheDocument();
+      expect(screen.getByText('Page')).toBeInTheDocument();
+    });
+
+    it('should not render breadcrumb when not provided', () => {
+      // TDD: Test breadcrumb optional
+      render(<PageHeader title="Page Title" />);
+      const breadcrumb = screen.queryByRole('navigation', { name: /breadcrumb/i });
+      expect(breadcrumb).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Variants', () => {
+    it('should apply default variant', () => {
+      // TDD: Test default variant
+      render(<PageHeader title="Page Title" variant="default" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+    });
+
+    it('should apply compact variant', () => {
+      // TDD: Test compact variant
+      render(<PageHeader title="Page Title" variant="compact" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+    });
+  });
+
+  describe('Layout', () => {
+    it('should have correct layout structure', () => {
+      // TDD: Test layout structure
+      render(
+        <PageHeader
+          title="Page Title"
+          description="Description"
+          actions={<Button>Action</Button>}
+        />
+      );
+
+      // Should have title
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+      // Should have description
+      expect(screen.getByText('Description')).toBeInTheDocument();
+      // Should have actions
+      expect(screen.getByText('Action')).toBeInTheDocument();
+    });
+
+    it('should handle missing description gracefully', () => {
+      // TDD: Test optional description
+      render(<PageHeader title="Page Title" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+      // Description should not be in document
+      const description = screen.queryByText(/description/i);
+      expect(description).not.toBeInTheDocument();
+    });
+
+    it('should handle missing actions gracefully', () => {
+      // TDD: Test optional actions
+      render(<PageHeader title="Page Title" />);
+      expect(screen.getByText('Page Title')).toBeInTheDocument();
+      // Actions should not be in document
+      const actions = screen.queryByRole('button');
+      expect(actions).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Custom ClassName', () => {
+    it('should apply custom className', () => {
+      // TDD: Test custom className
+      const { container } = render(<PageHeader title="Page Title" className="custom-header" />);
+      const header = container.firstChild as HTMLElement;
+      expect(header).toHaveClass('custom-header');
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('should have proper heading structure', () => {
+      // TDD: Test semantic HTML
+      render(<PageHeader title="Page Title" />);
+      const heading = screen.getByRole('heading', { name: 'Page Title' });
+      expect(heading).toBeInTheDocument();
+    });
+
+    it('should have proper heading level', () => {
+      // TDD: Test heading level
+      render(<PageHeader title="Page Title" />);
+      const heading = screen.getByRole('heading', { name: 'Page Title' });
+      expect(heading).toBeInTheDocument();
+      expect(heading.tagName.toLowerCase()).toBe('h1');
+    });
+  });
+});

package/src/ui/molecules/PageHeader/PageHeader.tsx

@@ -0,0 +1,100 @@
+/**
+ * PageHeader Component
+ * 
+ * Page header component with title, description, breadcrumb, and actions.
+ * 
+ * @see EPIC-004: PageHeader Component (Molecule)
+ */
+
+'use client';
+
+import React from 'react';
+import Breadcrumb from '../Breadcrumb/Breadcrumb';
+import { Text } from '../../atoms';
+import type { PageHeaderProps } from './types';
+import { cn, cva } from '../../utils';
+import { getSpacingClass } from '../../tokens/spacing';
+
+/**
+ * PageHeader Variants using CVA
+ * Type-safe variant system for PageHeader component
+ */
+const pageHeaderVariants = cva(
+  // Base classes
+  cn('w-full', 'flex', 'flex-col', 'gap-2'),
+  {
+    variants: {
+      variant: {
+        default: cn(getSpacingClass('base', 'mb')),
+        compact: cn(getSpacingClass('sm', 'mb')),
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+);
+
+/**
+ * PageHeader Component
+ * 
+ * Page header with title, description, breadcrumb, and actions.
+ * 
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   title="Page Title"
+ *   description="Page description"
+ *   breadcrumb={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Page', href: '/page' },
+ *   ]}
+ *   actions={<Button>Action</Button>}
+ * />
+ * ```
+ */
+export function PageHeader({
+  title,
+  description,
+  breadcrumb,
+  actions,
+  variant = 'default',
+  className,
+  ...props
+}: PageHeaderProps) {
+  return (
+    <div
+      className={cn(pageHeaderVariants({ variant }), className)}
+      {...props}
+    >
+      {/* Breadcrumb */}
+      {breadcrumb && breadcrumb.length > 0 && (
+        <Breadcrumb items={breadcrumb} />
+      )}
+
+      {/* Title and Actions Row */}
+      <div className="flex items-start justify-between gap-4">
+        {/* Title and Description */}
+        <div className="flex-1 min-w-0">
+          <Text variant="heading" as="h1" className="mb-2 text-2xl font-bold">
+            {title}
+          </Text>
+          {description && (
+            <Text variant="body" className="text-gray-600">
+              {description}
+            </Text>
+          )}
+        </div>
+
+        {/* Actions */}
+        {actions && (
+          <div className="flex items-center gap-2 flex-shrink-0">
+            {actions}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default PageHeader;

package/src/ui/molecules/PageHeader/index.ts

@@ -0,0 +1,9 @@
+/**
+ * PageHeader Exports
+ * 
+ * Exports for the PageHeader component and related types.
+ */
+
+export { default as PageHeader } from './PageHeader';
+export { PageHeader as PageHeaderComponent } from './PageHeader';
+export type { PageHeaderProps, PageHeaderVariant } from './types';

package/src/ui/molecules/PageHeader/types.ts

@@ -0,0 +1,51 @@
+/**
+ * PageHeader Types
+ * 
+ * Type definitions for the PageHeader component.
+ */
+
+import type { ReactNode } from 'react';
+import type { BreadcrumbItem } from '../Breadcrumb/Breadcrumb';
+
+/**
+ * PageHeader Variant
+ */
+export type PageHeaderVariant = 'default' | 'compact';
+
+/**
+ * PageHeader Props
+ * 
+ * @see EPIC-004: PageHeader Component (Molecule)
+ */
+export interface PageHeaderProps {
+  /**
+   * Page title (required)
+   */
+  title: string;
+
+  /**
+   * Page description (optional)
+   */
+  description?: string;
+
+  /**
+   * Breadcrumb items (optional)
+   */
+  breadcrumb?: BreadcrumbItem[];
+
+  /**
+   * Action buttons or content (optional)
+   */
+  actions?: ReactNode;
+
+  /**
+   * Visual variant
+   * @default 'default'
+   */
+  variant?: PageHeaderVariant;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}

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

@@ -1,14 +1,36 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { fn } from '@storybook/test';
+import { expect, userEvent, within, waitFor } from '@storybook/test';
 import { useState } from "react";
 import Pagination from "./Pagination";
 
 const meta: Meta<typeof Pagination> = {
-  title: "UI/Molecules/Pagination",
+  title: "Molecules/Pagination",
   component: Pagination,
   parameters: {
     docs: {
       description: {
-        component: "A pagination component for navigating through pages of data. Supports page info and ellipsis for large page counts.",
+        component: `
+## Pagination
+
+A pagination component for navigating through pages of data. Supports page info and ellipsis for large page counts.
+
+### Events
+
+| Event | Description | Parameters | When Fired |
+|-------|-------------|------------|------------|
+| \`onPageChange\` | Página mudou | \`(page: number) => void\` | Quando uma nova página é selecionada |
+
+### States
+
+| State | Description | How to Activate | Visual |
+|-------|-------------|-----------------|--------|
+| \`first-page\` | Primeira página | \`currentPage={1}\` | Botões de navegação anteriores desabilitados |
+| \`middle-page\` | Página do meio | \`currentPage\` entre primeira e última | Todos os botões de navegação habilitados |
+| \`last-page\` | Última página | \`currentPage={totalPages}\` | Botões de navegação seguintes desabilitados |
+| \`with-page-info\` | Com informações | \`showPageInfo={true}\` ou padrão | Informações de página visíveis |
+| \`without-page-info\` | Sem informações | \`showPageInfo={false}\` | Informações de página ocultas |
+        `,
       },
     },
   },
@@ -21,26 +43,81 @@ const meta: Meta<typeof Pagination> = {
       control: "number",
       description: "Total number of pages",
     },
+    totalItems: {
+      control: "number",
+      description: "Total number of items (for page info calculation)",
+    },
+    itemsPerPage: {
+      control: "number",
+      description: "Number of items per page",
+    },
     showPageInfo: {
       control: "boolean",
       description: "Whether to show page information",
     },
+    onPageChange: {
+      action: 'pageChanged',
+      description: 'Callback when page changes',
+      category: 'Events',
+    },
   },
 };
 
 export const Default: StoryObj<typeof Pagination> = {
   render: () => {
     const [page, setPage] = useState(1);
+    const itemsPerPage = 10;
+    const totalItems = 100;
+    const totalPages = Math.ceil(totalItems / itemsPerPage);
+    
+    // Simulate data for current page
+    const startIndex = (page - 1) * itemsPerPage;
+    const endIndex = Math.min(startIndex + itemsPerPage, totalItems);
+    const currentItems = Array.from({ length: endIndex - startIndex }, (_, i) => ({
+      id: startIndex + i + 1,
+      name: `Item ${startIndex + i + 1}`,
+    }));
+    
     return (
-      <Pagination
-        currentPage={page}
-        totalPages={10}
-        onPageChange={setPage}
-        totalItems={100}
-        itemsPerPage={10}
-      />
+      <div className="space-y-4">
+        <div className="border border-gray-200 rounded-lg overflow-hidden">
+          <table className="w-full">
+            <thead className="bg-gray-50">
+              <tr>
+                <th className="px-4 py-2 text-left text-sm font-medium">ID</th>
+                <th className="px-4 py-2 text-left text-sm font-medium">Name</th>
+              </tr>
+            </thead>
+            <tbody>
+              {currentItems.map((item) => (
+                <tr key={item.id} className="border-t border-gray-200">
+                  <td className="px-4 py-2 text-sm">{item.id}</td>
+                  <td className="px-4 py-2 text-sm">{item.name}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        <Pagination
+          currentPage={page}
+          totalPages={totalPages}
+          onPageChange={setPage}
+          totalItems={totalItems}
+          itemsPerPage={itemsPerPage}
+        />
+        <div className="text-sm text-gray-600">
+          Showing items {startIndex + 1} to {endIndex} of {totalItems}
+        </div>
+      </div>
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story: "Pagination with real data simulation. Navigate through pages to see different data displayed.",
+      },
+    },
+  },
 };
 
 export const FirstPage: StoryObj<typeof Pagination> = {
@@ -111,6 +188,234 @@ export const WithoutPageInfo: StoryObj<typeof Pagination> = {
       />
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story: "Pagination without page info display. Useful for compact layouts.",
+      },
+    },
+  },
+};
+
+export const WithManyPages: StoryObj<typeof Pagination> = {
+  render: () => {
+    const [page, setPage] = useState(1);
+    const totalPages = 50;
+    const itemsPerPage = 10;
+    const totalItems = totalPages * itemsPerPage;
+    
+    return (
+      <div className="space-y-4">
+        <Pagination
+          currentPage={page}
+          totalPages={totalPages}
+          onPageChange={setPage}
+          totalItems={totalItems}
+          itemsPerPage={itemsPerPage}
+        />
+        <div className="text-sm text-gray-600">
+          <p>Current page: <strong>{page}</strong> of {totalPages}</p>
+          <p>Try navigating to see ellipsis (...) when there are many pages</p>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Pagination with many pages (50). Demonstrates ellipsis and navigation with large page counts.",
+      },
+    },
+  },
+};
+
+export const InTable: StoryObj<typeof Pagination> = {
+  render: () => {
+    const [page, setPage] = useState(1);
+    const itemsPerPage = 5;
+    const totalItems = 47;
+    const totalPages = Math.ceil(totalItems / itemsPerPage);
+    
+    const allItems = Array.from({ length: totalItems }, (_, i) => ({
+      id: i + 1,
+      name: `User ${i + 1}`,
+      email: `user${i + 1}@example.com`,
+      role: ['Admin', 'User', 'Guest'][i % 3],
+    }));
+    
+    const startIndex = (page - 1) * itemsPerPage;
+    const currentItems = allItems.slice(startIndex, startIndex + itemsPerPage);
+    
+    return (
+      <div className="space-y-4">
+        <div className="border border-gray-200 rounded-lg overflow-hidden">
+          <table className="w-full">
+            <thead className="bg-gray-50">
+              <tr>
+                <th className="px-4 py-2 text-left text-sm font-medium">ID</th>
+                <th className="px-4 py-2 text-left text-sm font-medium">Name</th>
+                <th className="px-4 py-2 text-left text-sm font-medium">Email</th>
+                <th className="px-4 py-2 text-left text-sm font-medium">Role</th>
+              </tr>
+            </thead>
+            <tbody>
+              {currentItems.map((item) => (
+                <tr key={item.id} className="border-t border-gray-200 hover:bg-gray-50">
+                  <td className="px-4 py-2 text-sm">{item.id}</td>
+                  <td className="px-4 py-2 text-sm">{item.name}</td>
+                  <td className="px-4 py-2 text-sm">{item.email}</td>
+                  <td className="px-4 py-2 text-sm">
+                    <span className={`px-2 py-1 rounded text-xs ${
+                      item.role === 'Admin' ? 'bg-blue-100 text-blue-800' :
+                      item.role === 'User' ? 'bg-green-100 text-green-800' :
+                      'bg-gray-100 text-gray-800'
+                    }`}>
+                      {item.role}
+                    </span>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        <Pagination
+          currentPage={page}
+          totalPages={totalPages}
+          onPageChange={setPage}
+          totalItems={totalItems}
+          itemsPerPage={itemsPerPage}
+        />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Pagination integrated in a data table. Navigate through pages to see different rows displayed.",
+      },
+    },
+  },
+};
+
+// Event Stories
+export const WithEvents: StoryObj<typeof Pagination> = {
+  render: () => {
+    const [page, setPage] = useState(1);
+    const handlePageChange = fn((newPage: number) => {
+      setPage(newPage);
+    });
+    
+    return (
+      <div className="space-y-4">
+        <p className="text-sm text-gray-600">
+          Navigate through pages. Check the Actions panel to see events being fired.
+        </p>
+        <Pagination
+          currentPage={page}
+          totalPages={10}
+          onPageChange={handlePageChange}
+        />
+        <p className="text-sm text-gray-500">Current page: {page}</p>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const nextButton = canvas.getByLabelText(/next/i) || canvas.getByText(/next/i);
+    if (nextButton) {
+      await userEvent.click(nextButton);
+      await waitFor(() => {
+        expect(nextButton).toBeInTheDocument();
+      });
+    }
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates pagination events. Navigate through pages and check the Actions panel to see events being logged.',
+      },
+    },
+  },
+};
+
+// State Stories
+export const FirstPageState: StoryObj<typeof Pagination> = {
+  args: {
+    currentPage: 1,
+    totalPages: 10,
+    onPageChange: () => {},
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'First page state - previous navigation buttons are disabled.',
+      },
+    },
+  },
+};
+
+export const MiddlePageState: StoryObj<typeof Pagination> = {
+  args: {
+    currentPage: 5,
+    totalPages: 10,
+    onPageChange: () => {},
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Middle page state - all navigation buttons are enabled.',
+      },
+    },
+  },
+};
+
+export const LastPageState: StoryObj<typeof Pagination> = {
+  args: {
+    currentPage: 10,
+    totalPages: 10,
+    onPageChange: () => {},
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Last page state - next navigation buttons are disabled.',
+      },
+    },
+  },
+};
+
+export const WithPageInfoState: StoryObj<typeof Pagination> = {
+  args: {
+    currentPage: 5,
+    totalPages: 10,
+    totalItems: 100,
+    itemsPerPage: 10,
+    showPageInfo: true,
+    onPageChange: () => {},
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'With page info state - page information is displayed.',
+      },
+    },
+  },
+};
+
+export const WithoutPageInfoState: StoryObj<typeof Pagination> = {
+  args: {
+    currentPage: 5,
+    totalPages: 10,
+    showPageInfo: false,
+    onPageChange: () => {},
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Without page info state - page information is hidden.',
+      },
+    },
+  },
 };
 
 export default meta;

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

@@ -107,6 +107,6 @@ describe("Pagination", () => {
     );
     const currentPageButton = screen.getByLabelText("Go to page 3");
     expect(currentPageButton).toHaveAttribute("aria-current", "page");
-    expect(currentPageButton).toHaveClass("bg-indigo-600", "text-white");
+    expect(currentPageButton).toHaveClass("bg-indigo-500", "text-white");
   });
 });