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

package/src/ui/atoms/Text/Text.test.tsx

@@ -1,47 +1,63 @@
-import { render } from "@testing-library/react";
-
-import Text from "./Text";
-
-describe("UI / atom / Text", () => {
-  const TEXT = "Test";
-
-  it("should render properly", () => {
-    const { getByText } = render(<Text>{TEXT}</Text>);
-
-    expect(getByText(TEXT)).toBeInTheDocument();
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import Text from './Text';
+
+describe('Text', () => {
+  it('renders text content', () => {
+    render(<Text>Hello World</Text>);
+    expect(screen.getByText('Hello World')).toBeInTheDocument();
   });
 
-  it("should change the tag accordingly", () => {
-    const heading = render(<Text variant="heading">{TEXT}</Text>);
-    const regular = render(<Text>{TEXT}</Text>);
-    const listItem = render(<Text variant="list">{TEXT}</Text>);
-
-    expect(heading.container.querySelector("h2")).toBeInTheDocument();
-    expect(regular.container.querySelector("p")).toBeInTheDocument();
-    expect(listItem.container.querySelector("li")).toBeInTheDocument();
+  it('renders as paragraph by default', () => {
+    const { container } = render(<Text>Content</Text>);
+    const text = container.querySelector('p');
+    expect(text).toBeInTheDocument();
   });
 
-  it("should force the tag accordingly", () => {
-    const { container } = render(<Text as="h1">{TEXT}</Text>);
+  it('renders as heading when variant is heading', () => {
+    const { container } = render(<Text variant="heading">Heading</Text>);
+    const text = container.querySelector('h2');
+    expect(text).toBeInTheDocument();
+  });
 
-    expect(container.querySelector("h1")).toBeInTheDocument();
+  it('renders as list item when variant is list', () => {
+    const { container } = render(<Text variant="list">List item</Text>);
+    const text = container.querySelector('li');
+    expect(text).toBeInTheDocument();
   });
 
-  it("should make the text bold", () => {
-    const { container } = render(<Text bold>{TEXT}</Text>);
+  it('renders as custom element when as prop is provided', () => {
+    const { container } = render(<Text as="span">Content</Text>);
+    const text = container.querySelector('span');
+    expect(text).toBeInTheDocument();
+  });
 
-    expect(container.querySelector(".font-bold")).toBeInTheDocument();
+  it('applies bold class when bold prop is true', () => {
+    const { container } = render(<Text bold>Bold text</Text>);
+    const text = container.querySelector('p');
+    expect(text).toHaveClass('font-bold');
   });
 
-  it("should make the text italic", () => {
-    const { container } = render(<Text italic>{TEXT}</Text>);
+  it('applies italic class when italic prop is true', () => {
+    const { container } = render(<Text italic>Italic text</Text>);
+    const text = container.querySelector('p');
+    expect(text).toHaveClass('italic');
+  });
 
-    expect(container.querySelector(".italic")).toBeInTheDocument();
+  it('applies color class when color prop is provided', () => {
+    const { container } = render(<Text color="red-500">Colored text</Text>);
+    const text = container.querySelector('p');
+    expect(text).toHaveClass('text-red-500');
   });
 
-  it("should change the color", () => {
-    const { container } = render(<Text color="red-500">{TEXT}</Text>);
+  it('applies custom className', () => {
+    const { container } = render(<Text className="custom-class">Content</Text>);
+    const text = container.querySelector('p');
+    expect(text).toHaveClass('custom-class');
+  });
 
-    expect(container.querySelector(".text-red-500")).toBeInTheDocument();
+  it('passes through HTML attributes', () => {
+    render(<Text data-testid="text">Content</Text>);
+    expect(screen.getByTestId('text')).toBeInTheDocument();
   });
-});
+});

package/src/ui/atoms/Textarea/Textarea.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react";
 import Textarea from "./Textarea";
 
 const meta: Meta<typeof Textarea> = {
-  title: "UI/Atoms/Textarea",
+  title: "Atoms/Textarea",
   component: Textarea,
   parameters: {
     docs: {

package/src/ui/atoms/Tooltip/Tooltip.stories.tsx

@@ -7,12 +7,26 @@ const meta = {
   component: Tooltip,
   parameters: {
     layout: "centered",
+    docs: {
+      description: {
+        component: "A tooltip component that displays additional information on hover or focus. Supports keyboard navigation and includes proper ARIA attributes. Tooltips appear immediately on focus (no delay) for better keyboard accessibility.",
+      },
+    },
   },
   tags: ["autodocs"],
   argTypes: {
     position: {
       control: "select",
       options: ["top", "bottom", "left", "right"],
+      description: "Position of the tooltip relative to the trigger element",
+    },
+    delay: {
+      control: "number",
+      description: "Delay in milliseconds before showing tooltip on hover (not applied on focus)",
+    },
+    'aria-label': {
+      control: "text",
+      description: "Accessible label for screen readers",
     },
   },
 } satisfies Meta<typeof Tooltip>;
@@ -58,3 +72,33 @@ export const Right: Story = {
     position: "right",
   },
 };
+
+export const WithCustomDelay: Story = {
+  args: {
+    content: "This tooltip has a 500ms delay",
+    children: <Button>Hover me (wait 500ms)</Button>,
+    delay: 500,
+  },
+};
+
+export const KeyboardAccessible: Story = {
+  args: {
+    content: "Press Tab to focus and see tooltip immediately",
+    children: <Button>Focus me with Tab</Button>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Tab to focus the button. The tooltip appears immediately without delay for keyboard users.",
+      },
+    },
+  },
+};
+
+export const WithAriaLabel: Story = {
+  args: {
+    content: "Additional information",
+    children: <Button>Button with tooltip</Button>,
+    'aria-label': "Button that shows additional information on hover",
+  },
+};

package/src/ui/atoms/Tooltip/Tooltip.tsx

@@ -1,13 +1,14 @@
 'use client';
 
-import type { HTMLAttributes, ReactNode } from "react";
-import { useState } from "react";
+import type { HTMLAttributes, ReactNode, KeyboardEvent, FocusEvent, ReactElement } from "react";
+import { useState, useRef, useEffect, cloneElement, isValidElement } from "react";
 
 export interface TooltipProps extends HTMLAttributes<HTMLDivElement> {
   content: string;
   children: ReactNode;
   position?: "top" | "bottom" | "left" | "right";
   delay?: number;
+  'aria-label'?: string;
 }
 
 /**
@@ -29,10 +30,16 @@ export default function Tooltip({
   position = "top",
   delay = 200,
   className = "",
+  'aria-label': _ariaLabel,
   ...props
 }: TooltipProps) {
   const [isVisible, setIsVisible] = useState(false);
-  const [timeoutId, setTimeoutId] = useState<number | null>(null);
+  const [timeoutId, setTimeoutId] = useState<NodeJS.Timeout | null>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+
+  // Generate unique ID for tooltip
+  const tooltipId = `tooltip-${Math.random().toString(36).substr(2, 9)}`;
 
   const handleMouseEnter = () => {
     const id = setTimeout(() => {
@@ -49,6 +56,43 @@ export default function Tooltip({
     setIsVisible(false);
   };
 
+  const handleFocus = () => {
+    // Show tooltip immediately on focus (no delay for keyboard users)
+    setIsVisible(true);
+  };
+
+  const handleBlur = () => {
+    setIsVisible(false);
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      setIsVisible(false);
+      triggerRef.current?.blur();
+    }
+  };
+
+  // Close tooltip when clicking outside
+  useEffect(() => {
+    if (!isVisible) return;
+
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        tooltipRef.current &&
+        !tooltipRef.current.contains(event.target as Node) &&
+        triggerRef.current &&
+        !triggerRef.current.contains(event.target as Node)
+      ) {
+        setIsVisible(false);
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [isVisible]);
+
   const positionClasses: Record<NonNullable<TooltipProps["position"]>, string> = {
     top: "bottom-full left-1/2 transform -translate-x-1/2 mb-2",
     bottom: "top-full left-1/2 transform -translate-x-1/2 mt-2",
@@ -63,22 +107,66 @@ export default function Tooltip({
     right: "right-full top-1/2 transform -translate-y-1/2 border-r-gray-900",
   };
 
+  // Clone children to add accessibility props
+  const childrenWithProps = isValidElement(children)
+    ? (() => {
+        const childElement = children as ReactElement<HTMLAttributes<HTMLElement> & { ref?: React.Ref<HTMLElement> }>;
+        const existingProps = childElement.props;
+        const existingRef = existingProps.ref;
+        
+        return cloneElement(childElement, {
+          ref: (node: HTMLElement | null) => {
+            triggerRef.current = node;
+            // Preserve existing ref if any
+            if (typeof existingRef === 'function') {
+              existingRef(node);
+            } else if (existingRef && typeof existingRef === 'object' && 'current' in existingRef) {
+              (existingRef as React.MutableRefObject<HTMLElement | null>).current = node;
+            }
+          },
+          'aria-describedby': isVisible ? tooltipId : existingProps['aria-describedby'],
+          onMouseEnter: (e: React.MouseEvent<HTMLElement>) => {
+            handleMouseEnter();
+            existingProps.onMouseEnter?.(e);
+          },
+          onMouseLeave: (e: React.MouseEvent<HTMLElement>) => {
+            handleMouseLeave();
+            existingProps.onMouseLeave?.(e);
+          },
+          onFocus: (e: FocusEvent<HTMLElement>) => {
+            handleFocus();
+            existingProps.onFocus?.(e);
+          },
+          onBlur: (e: FocusEvent<HTMLElement>) => {
+            handleBlur();
+            existingProps.onBlur?.(e);
+          },
+          onKeyDown: (e: KeyboardEvent<HTMLElement>) => {
+            handleKeyDown(e);
+            existingProps.onKeyDown?.(e);
+          },
+        } as Partial<typeof existingProps>);
+      })()
+    : children;
+
   return (
     <div
       className={`relative inline-block ${className}`}
-      onMouseEnter={handleMouseEnter}
-      onMouseLeave={handleMouseLeave}
       {...props}
     >
-      {children}
+      {childrenWithProps}
       {isVisible && (
         <div
+          ref={tooltipRef}
+          id={tooltipId}
           className={`absolute z-50 px-2 py-1 text-xs text-white bg-gray-900 rounded shadow-lg whitespace-nowrap ${positionClasses[position]}`}
           role="tooltip"
+          aria-live="polite"
         >
           {content}
           <div
             className={`absolute w-0 h-0 border-4 border-transparent ${arrowClasses[position]}`}
+            aria-hidden="true"
           />
         </div>
       )}

package/src/ui/atoms/index.ts

@@ -1,17 +1,21 @@
 export { default as Info } from "./Info/Info";
+export type { InfoProps } from "./Info/Info";
 
 export { default as Text } from "./Text/Text";
 
 export { default as Input } from "./Input/Input";
-export type { InputProps } from "./Input/Input";
+export type { InputProps, InputSize, InputVariant, InputState } from "./Input/Input";
 
 export { default as Button } from "./Button/Button";
+export type { ButtonProps, ButtonVariant, ButtonSize } from "./Button/Button";
 
 export { default as BoxWrapper } from "./BoxWrapper/BoxWrapper";
+export type { BoxWrapperProps } from "./BoxWrapper/BoxWrapper";
 
 export { default as Badge } from "./Badge/Badge";
 
 export { default as Select } from "./Select/Select";
+export type { SelectProps, SelectOption, SelectOptionGroup, SelectSize } from "./Select/Select";
 
 export { default as Textarea } from "./Textarea/Textarea";
 
@@ -25,11 +29,10 @@ export { default as Tooltip } from "./Tooltip/Tooltip";
 export type { TooltipProps } from "./Tooltip/Tooltip";
 
 export { default as Skeleton } from "./Skeleton/Skeleton";
+export { default as Spinner } from "./Spinner/Spinner";
+export type { SpinnerProps, SpinnerSize, SpinnerVariant } from "./Spinner/Spinner";
 export type { SkeletonProps } from "./Skeleton/Skeleton";
 
-export { default as SidebarItem } from "./SidebarItem/SidebarItem";
-export type { SidebarItemProps } from "./SidebarItem/SidebarItem";
-
 export { default as Collapsible } from "./Collapsible/Collapsible";
 export type { CollapsibleProps } from "./Collapsible/Collapsible";
 
@@ -38,3 +41,23 @@ export type { CheckboxProps } from "./Checkbox/Checkbox";
 
 export { default as Radio } from "./Radio/Radio";
 export type { RadioProps } from "./Radio/Radio";
+
+export { default as Progress } from "./Progress/Progress";
+export type { ProgressProps, ProgressVariant, ProgressSize } from "./Progress/Progress";
+
+export { default as Switch } from "./Switch/Switch";
+export type { SwitchProps, SwitchSize } from "./Switch/Switch";
+
+export { default as Separator } from "./Separator/Separator";
+export type { SeparatorProps, SeparatorOrientation, SeparatorVariant } from "./Separator/Separator";
+
+export { default as Accordion } from "./Accordion/Accordion";
+export type { AccordionProps, AccordionItem, AccordionType } from "./Accordion/Accordion";
+
+export { default as Slider } from "./Slider/Slider";
+export type { SliderProps, SliderVariant, SliderSize } from "./Slider/Slider";
+
+export { default as Popover } from "./Popover/Popover";
+export type { PopoverProps, PopoverPlacement } from "./Popover/Popover";
+
+export * from "./Avatar";

package/src/ui/index.ts

@@ -9,10 +9,15 @@ export * from "./tokens/breakpoints";
 export * from "./tokens/tokens.factory";
 export * from "./tokens/themes/light";
 export * from "./tokens/themes/dark";
-export * from "./providers/ThemeProvider";
+export * from "./providers";
+export * from "./themes";
 
 // Export helper functions for convenience
 export { getSpacingClass, getSpacing } from "./tokens/spacing";
 export { getTypographyClasses, getTypography } from "./tokens/typography";
 export { getColorClass, getColor } from "./tokens/colors";
 export { getBreakpoint, getMediaQuery } from "./tokens/breakpoints";
+export { getAnimationClass, getAnimation, getTransitionClass } from "./tokens/animations";
+export { getZIndexClass, getZIndex } from "./tokens/z-index";
+export { getOpacityClass, getOpacity } from "./tokens/opacity";
+export { getGradientClass, getGradient } from "./tokens/gradients";

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

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react";
 import Breadcrumb from "./Breadcrumb";
 
 const meta: Meta<typeof Breadcrumb> = {
-  title: "UI/Molecules/Breadcrumb",
+  title: "Molecules/Breadcrumb",
   component: Breadcrumb,
   parameters: {
     docs: {

package/src/ui/molecules/Breadcrumb/Breadcrumb.tsx

@@ -49,7 +49,7 @@ export default function Breadcrumb({
   ].filter(Boolean).join(" ");
 
   return (
-    <nav aria-label="Breadcrumb" className={classes} {...(props as any)}>
+    <nav aria-label="Breadcrumb" className={classes} {...props}>
       <ol className="flex items-center space-x-2">
         {items.map((item, index) => {
           const isLast = index === items.length - 1;

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

@@ -3,7 +3,7 @@ import Card from "./Card";
 import { Text, Button } from "../../atoms";
 
 const meta: Meta<typeof Card> = {
-  title: "UI/Molecules/Card",
+  title: "Molecules/Card",
   component: Card,
   parameters: {
     docs: {
@@ -23,6 +23,18 @@ const meta: Meta<typeof Card> = {
       options: ["none", "small", "medium", "large"],
       description: "Padding size",
     },
+    onClick: {
+      control: false,
+      description: "Click handler. When provided, card becomes interactive with keyboard support.",
+    },
+    'aria-label': {
+      control: "text",
+      description: "Accessible label for interactive cards",
+    },
+    'aria-labelledby': {
+      control: "text",
+      description: "ID of element that labels the card",
+    },
   },
 };
 
@@ -114,4 +126,40 @@ export const NoPadding: StoryObj<typeof Card> = {
   },
 };
 
+export const Interactive: StoryObj<typeof Card> = {
+  args: {
+    variant: "hover",
+    onClick: () => alert("Card clicked!"),
+    'aria-label': "Clickable card example",
+    children: (
+      <>
+        <Text as="h3" className="text-lg font-semibold mb-2">Interactive Card</Text>
+        <Text as="p" className="text-gray-600">This card is clickable. Press Enter or Space when focused to activate.</Text>
+      </>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Interactive cards support keyboard navigation. Tab to focus, then press Enter or Space to activate.",
+      },
+    },
+  },
+};
+
+export const WithAriaLabel: StoryObj<typeof Card> = {
+  args: {
+    variant: "hover",
+    onClick: () => alert("Card clicked!"),
+    'aria-label': "Product card: Premium Plan - $99/month",
+    children: (
+      <>
+        <Text as="h3" className="text-lg font-semibold mb-2">Premium Plan</Text>
+        <Text as="p" className="text-gray-600 mb-2">$99/month</Text>
+        <Text as="p" className="text-sm text-gray-500">Includes all features</Text>
+      </>
+    ),
+  },
+};
+
 export default meta;

package/src/ui/molecules/Card/Card.tsx

@@ -1,8 +1,12 @@
+import { memo, useMemo, useCallback } from 'react';
 import type { HTMLAttributes } from "react";
 
 interface Props extends HTMLAttributes<HTMLDivElement> {
   variant?: "default" | "hover" | "selected";
   padding?: "none" | "small" | "medium" | "large";
+  onClick?: () => void;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
 }
 
 /**
@@ -11,6 +15,7 @@ interface Props extends HTMLAttributes<HTMLDivElement> {
  * A versatile card component for displaying content in containers.
  * Follows Atomic Design principles as a Molecule component.
  * Can be used to replace BoxWrapper in many cases with more flexibility.
+ * Optimized with React.memo to prevent unnecessary re-renders.
  * 
  * @example
  * ```tsx
@@ -20,10 +25,13 @@ interface Props extends HTMLAttributes<HTMLDivElement> {
  * </Card>
  * ```
  */
-export default function Card({
+const Card = memo(function Card({
   variant = "default",
   padding = "medium",
   className = "",
+  onClick,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
   children,
   ...props
 }: Props) {
@@ -48,16 +56,43 @@ export default function Card({
     large: "p-6",
   };
 
-  const classes = [
+  const isInteractive = useMemo(() => 
+    onClick !== undefined || variant === "hover",
+    [onClick, variant]
+  );
+  const role = isInteractive ? "button" : undefined;
+  const tabIndex = isInteractive ? 0 : undefined;
+
+  const classes = useMemo(() => [
     ...baseClasses,
     variantClasses[variant],
     paddingClasses[padding],
     className,
-  ].filter(Boolean).join(" ");
+  ].filter(Boolean).join(" "), [variant, padding, className]);
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (isInteractive && (e.key === 'Enter' || e.key === ' ')) {
+      e.preventDefault();
+      onClick?.();
+    }
+  }, [isInteractive, onClick]);
 
   return (
-    <div className={classes} {...props}>
+    <div
+      className={classes}
+      role={role}
+      tabIndex={tabIndex}
+      onClick={onClick}
+      onKeyDown={handleKeyDown}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      {...props}
+    >
       {children}
     </div>
   );
-}
+});
+
+Card.displayName = 'Card';
+
+export default Card;