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

package/src/ui/organisms/Stepper/Stepper.tsx

@@ -0,0 +1,323 @@
+'use client';
+
+import { useState, type ReactNode } from 'react';
+import { Check } from 'lucide-react';
+import { getColorClass } from '../../tokens/colors';
+import { getSpacingClass } from '../../tokens/spacing';
+import { getRadiusClass } from '../../tokens/radius';
+import { getAnimationClass } from '../../tokens/animations';
+import Button from '../../atoms/Button/Button';
+import Separator from '../../atoms/Separator/Separator';
+
+export type StepperStatus = 'pending' | 'active' | 'completed' | 'error';
+
+export interface StepperStep {
+  id: string;
+  title: string;
+  description?: string;
+  content: ReactNode;
+  status?: StepperStatus;
+  disabled?: boolean;
+}
+
+export interface StepperProps {
+  steps: StepperStep[];
+  currentStep?: number;
+  defaultCurrentStep?: number;
+  onStepChange?: (stepIndex: number) => void;
+  onComplete?: () => void;
+  allowNavigation?: boolean;
+  showStepNumbers?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+}
+
+/**
+ * Stepper Component
+ * 
+ * A multi-step wizard component for guided workflows.
+ * Supports validation, navigation, and completion callbacks.
+ * Follows Atomic Design principles as an Organism component.
+ * 
+ * @example
+ * ```tsx
+ * <Stepper
+ *   steps={[
+ *     { id: '1', title: 'Step 1', content: <div>Content 1</div> },
+ *     { id: '2', title: 'Step 2', content: <div>Content 2</div> },
+ *   ]}
+ *   onComplete={() => console.log('Completed!')}
+ * />
+ * ```
+ */
+export default function Stepper({
+  steps,
+  currentStep: controlledCurrentStep,
+  defaultCurrentStep = 0,
+  onStepChange,
+  onComplete,
+  allowNavigation = true,
+  showStepNumbers = true,
+  orientation = 'horizontal',
+  className = '',
+}: StepperProps) {
+  const [internalCurrentStep, setInternalCurrentStep] = useState(defaultCurrentStep);
+
+  const isControlled = controlledCurrentStep !== undefined;
+  const currentStepIndex = isControlled ? controlledCurrentStep : internalCurrentStep;
+
+  const getStepStatus = (index: number): StepperStatus => {
+    if (index < currentStepIndex) return 'completed';
+    if (index === currentStepIndex) return 'active';
+    return 'pending';
+  };
+
+  const handleNext = () => {
+    if (currentStepIndex < steps.length - 1) {
+      const nextStep = currentStepIndex + 1;
+      if (!isControlled) {
+        setInternalCurrentStep(nextStep);
+      }
+      onStepChange?.(nextStep);
+    } else {
+      onComplete?.();
+    }
+  };
+
+  const handlePrevious = () => {
+    if (currentStepIndex > 0) {
+      const prevStep = currentStepIndex - 1;
+      if (!isControlled) {
+        setInternalCurrentStep(prevStep);
+      }
+      onStepChange?.(prevStep);
+    }
+  };
+
+  const handleStepClick = (index: number) => {
+    if (!allowNavigation) return;
+    if (steps[index].disabled) return;
+    
+    if (!isControlled) {
+      setInternalCurrentStep(index);
+    }
+    onStepChange?.(index);
+  };
+
+  const currentStep = steps[currentStepIndex];
+  const isFirstStep = currentStepIndex === 0;
+  const isLastStep = currentStepIndex === steps.length - 1;
+
+  if (orientation === 'vertical') {
+    return (
+      <div className={`flex gap-4 ${className}`}>
+        {/* Steps List */}
+        <div className="flex flex-col">
+          {steps.map((step, index) => {
+            const status = step.status || getStepStatus(index);
+            const isActive = index === currentStepIndex;
+
+            return (
+              <div key={step.id} className="flex items-start gap-3">
+                {/* Step Indicator */}
+                <div className="flex flex-col items-center">
+                  <button
+                    type="button"
+                    onClick={() => handleStepClick(index)}
+                    disabled={!allowNavigation || step.disabled}
+                    className={`
+                      flex
+                      items-center
+                      justify-center
+                      w-10
+                      h-10
+                      ${getRadiusClass('full')}
+                      border-2
+                      ${getAnimationClass('base')}
+                      ${status === 'completed'
+                        ? `${getColorClass('success', 'DEFAULT', 'bg')} ${getColorClass('success', 'DEFAULT', 'border')} text-white`
+                        : status === 'active'
+                        ? `${getColorClass('primary', 'DEFAULT', 'bg')} ${getColorClass('primary', 'DEFAULT', 'border')} text-white`
+                        : status === 'error'
+                        ? `${getColorClass('error', 'DEFAULT', 'bg')} ${getColorClass('error', 'DEFAULT', 'border')} text-white`
+                        : 'bg-white border-gray-300 text-gray-400'
+                      }
+                      ${!allowNavigation || step.disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'}
+                    `}
+                  >
+                    {status === 'completed' ? (
+                      <Check className="h-5 w-5" />
+                    ) : showStepNumbers ? (
+                      index + 1
+                    ) : null}
+                  </button>
+                  {index < steps.length - 1 && (
+                    <div
+                      className={`
+                        w-0.5
+                        h-12
+                        mt-2
+                        ${status === 'completed' ? getColorClass('success', 'DEFAULT', 'bg') : 'bg-gray-300'}
+                      `}
+                    />
+                  )}
+                </div>
+
+                {/* Step Content */}
+                <div className="flex-1 pb-8">
+                  <button
+                    type="button"
+                    onClick={() => handleStepClick(index)}
+                    disabled={!allowNavigation || step.disabled}
+                    className={`
+                      text-left
+                      ${isActive ? 'font-semibold' : 'font-medium'}
+                      ${status === 'active' ? getColorClass('primary', 'DEFAULT', 'text') : 'text-gray-700'}
+                      ${!allowNavigation || step.disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'}
+                    `}
+                  >
+                    {step.title}
+                  </button>
+                  {step.description && (
+                    <p className="text-sm text-gray-500 mt-1">{step.description}</p>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+
+        {/* Step Content */}
+        <div className="flex-1">
+          <div className={`
+            ${getSpacingClass('lg', 'p')}
+            border
+            border-gray-200
+            ${getRadiusClass('lg')}
+            bg-white
+          `}>
+            {currentStep.content}
+          </div>
+
+          {/* Navigation */}
+          <div className={`flex justify-between mt-4 ${getSpacingClass('base', 'gap')}`}>
+            <Button
+              variant="outline"
+              onClick={handlePrevious}
+              disabled={isFirstStep}
+            >
+              Previous
+            </Button>
+            <Button
+              variant="primary"
+              onClick={handleNext}
+            >
+              {isLastStep ? 'Complete' : 'Next'}
+            </Button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // Horizontal orientation
+  return (
+    <div className={`space-y-6 ${className}`}>
+      {/* Steps List */}
+      <div className="flex items-center">
+        {steps.map((step, index) => {
+          const status = step.status || getStepStatus(index);
+          const isActive = index === currentStepIndex;
+
+          return (
+            <div key={step.id} className="flex items-center flex-1">
+              <div className="flex flex-col items-center flex-1">
+                <button
+                  type="button"
+                  onClick={() => handleStepClick(index)}
+                  disabled={!allowNavigation || step.disabled}
+                  className={`
+                    flex
+                    items-center
+                    justify-center
+                    w-10
+                    h-10
+                    ${getRadiusClass('full')}
+                    border-2
+                    ${getAnimationClass('base')}
+                    ${status === 'completed'
+                      ? `${getColorClass('success', 'DEFAULT', 'bg')} ${getColorClass('success', 'DEFAULT', 'border')} text-white`
+                      : status === 'active'
+                      ? `${getColorClass('primary', 'DEFAULT', 'bg')} ${getColorClass('primary', 'DEFAULT', 'border')} text-white`
+                      : status === 'error'
+                      ? `${getColorClass('error', 'DEFAULT', 'bg')} ${getColorClass('error', 'DEFAULT', 'border')} text-white`
+                      : 'bg-white border-gray-300 text-gray-400'
+                    }
+                    ${!allowNavigation || step.disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'}
+                  `}
+                >
+                  {status === 'completed' ? (
+                    <Check className="h-5 w-5" />
+                  ) : showStepNumbers ? (
+                    index + 1
+                  ) : null}
+                </button>
+                <div className={`mt-2 text-center ${getSpacingClass('sm', 'px')}`}>
+                  <p
+                    className={`
+                      text-sm
+                      font-medium
+                      ${isActive ? getColorClass('primary', 'DEFAULT', 'text') : 'text-gray-600'}
+                    `}
+                  >
+                    {step.title}
+                  </p>
+                  {step.description && (
+                    <p className="text-xs text-gray-500 mt-1">{step.description}</p>
+                  )}
+                </div>
+              </div>
+              {index < steps.length - 1 && (
+                <div className={`flex-1 mx-2 ${getSpacingClass('base', 'mx')}`}>
+                  <Separator
+                    className={`
+                      ${status === 'completed' ? getColorClass('success', 'DEFAULT', 'border') : 'border-gray-300'}
+                    `}
+                  />
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Step Content */}
+      <div className={`
+        ${getSpacingClass('lg', 'p')}
+        border
+        border-gray-200
+        ${getRadiusClass('lg')}
+        bg-white
+      `}>
+        {currentStep.content}
+      </div>
+
+      {/* Navigation */}
+      <div className={`flex justify-between ${getSpacingClass('base', 'gap')}`}>
+        <Button
+          variant="outline"
+          onClick={handlePrevious}
+          disabled={isFirstStep}
+        >
+          Previous
+        </Button>
+        <Button
+          variant="primary"
+          onClick={handleNext}
+        >
+          {isLastStep ? 'Complete' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/ui/organisms/Stepper/index.ts

@@ -0,0 +1,2 @@
+export { default } from './Stepper';
+export type { StepperProps, StepperStep, StepperStatus } from './Stepper';

package/src/ui/organisms/Table/Table.mdx

@@ -0,0 +1,154 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Table" />
+
+# Table
+
+A powerful and flexible table component with sorting, filtering, pagination, and responsive design capabilities.
+
+## Features
+
+- **Sorting**: Click column headers to sort data
+- **Loading States**: Built-in loading skeleton
+- **Custom Rendering**: Customize cell rendering with render functions
+- **Responsive**: Adapts to different screen sizes
+- **Accessible**: Full ARIA support and keyboard navigation
+- **Pagination**: Built-in pagination support
+- **Actions**: Row-level actions support
+
+## Basic Usage
+
+```tsx
+import { Table } from '@fabio.caffarello/react-design-system';
+
+const data = [
+  { id: '1', name: 'Item 1', status: 'Active' },
+  { id: '2', name: 'Item 2', status: 'Inactive' },
+];
+
+const columns = [
+  { key: 'name', label: 'Name' },
+  { key: 'status', label: 'Status' },
+];
+
+<Table columns={columns} data={data} />
+```
+
+## Sorting
+
+Enable sorting by providing a `sortable` property on columns:
+
+```tsx
+const columns = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'status', label: 'Status', sortable: true },
+];
+
+<Table 
+  columns={columns} 
+  data={data}
+  onSort={(key, direction) => {
+    // Handle sorting
+  }}
+/>
+```
+
+## Custom Cell Rendering
+
+Customize how cells are rendered using the `render` function:
+
+```tsx
+const columns = [
+  { 
+    key: 'status', 
+    label: 'Status',
+    render: (value, row) => (
+      <Badge variant={value === 'Active' ? 'success' : 'default'}>
+        {value}
+      </Badge>
+    )
+  },
+];
+```
+
+## Loading State
+
+Show a loading skeleton while data is being fetched:
+
+```tsx
+<Table 
+  columns={columns} 
+  data={data}
+  loading={true}
+/>
+```
+
+## Pagination
+
+Integrate with pagination components:
+
+```tsx
+import { Table, TablePagination } from '@fabio.caffarello/react-design-system';
+
+<>
+  <Table columns={columns} data={currentPageData} />
+  <TablePagination
+    currentPage={page}
+    totalPages={totalPages}
+    onPageChange={setPage}
+  />
+</>
+```
+
+## Actions
+
+Add row-level actions:
+
+```tsx
+import { Table, TableActions } from '@fabio.caffarello/react-design-system';
+
+<Table
+  columns={columns}
+  data={data}
+  actions={(row) => (
+    <TableActions
+      items={[
+        { label: 'Edit', onClick: () => handleEdit(row) },
+        { label: 'Delete', onClick: () => handleDelete(row) },
+      ]}
+    />
+  )}
+/>
+```
+
+## Accessibility
+
+The Table component follows ARIA best practices:
+
+- Uses `role="table"` for the table element
+- Uses `role="columnheader"` for sortable headers
+- Provides `aria-sort` attributes for sort state
+- Supports keyboard navigation
+- Associates headers with cells via `aria-labelledby`
+
+### Keyboard Navigation
+
+- **Tab**: Navigate between interactive elements
+- **Enter/Space**: Activate sortable column headers
+- **Arrow Keys**: Navigate between cells (when implemented)
+
+## Responsive Design
+
+The table automatically adapts to smaller screens:
+
+- On mobile, consider using a card-based layout
+- Horizontal scrolling is available for wide tables
+- Use responsive column visibility
+
+## Best Practices
+
+1. **Column Keys**: Always use unique, stable keys for columns
+2. **Data Structure**: Keep data structure consistent across rows
+3. **Performance**: For large datasets, implement virtual scrolling
+4. **Accessibility**: Always provide accessible labels and descriptions
+5. **Loading States**: Always show loading states for async data