@brcarddev/frontend-commons 1.0.2

package/src/components/atoms/CheckIcon/check-icon.test.tsx

@@ -0,0 +1,270 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+
+import { CheckIcon } from './check-icon';
+
+describe('<CheckIcon />', () => {
+  const renderCheckIcon = (props = {}) =>
+    render(<CheckIcon data-testid="check-icon" {...props} />);
+
+  describe('Rendering', () => {
+    it('renders correctly with default props', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toBeInTheDocument();
+      expect(checkIcon).toHaveAttribute('type', 'button');
+    });
+
+    it('renders as a button element', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon.tagName).toBe('BUTTON');
+    });
+
+    it('applies custom className', () => {
+      renderCheckIcon({ className: 'custom-class' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveClass('custom-class');
+    });
+
+    it('has cursor-pointer and flex styles by default', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveClass('cursor-pointer', 'rounded-full', 'flex', 'items-center', 'justify-center');
+    });
+  });
+
+  describe('Sizes', () => {
+    it.each([
+      [ 'sm', 'size-6' ],
+      [ 'md', 'size-7' ],
+      [ 'lg', 'size-8' ],
+    ] as const)('applies correct size class for %s size', (size, expectedClass) => {
+      renderCheckIcon({ size });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveClass(expectedClass);
+    });
+
+    it('uses medium size as default', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveClass('size-7');
+    });
+  });
+
+  describe('Variants', () => {
+    describe('outline variant', () => {
+      it('applies outline variant styles by default', () => {
+        renderCheckIcon();
+
+        const checkIcon = screen.getByTestId('check-icon');
+        expect(checkIcon).toHaveClass('bg-white', 'border-3', 'border-gray-400');
+      });
+
+      it('applies outline variant styles explicitly', () => {
+        renderCheckIcon({ variant: 'outline' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+        expect(checkIcon).toHaveClass('bg-white', 'border-3', 'border-gray-400');
+      });
+
+      it('shows check icon with correct styles when unchecked', () => {
+        renderCheckIcon({ variant: 'outline' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+        const checkSvg = checkIcon.querySelector('svg');
+
+        expect(checkSvg).toBeInTheDocument();
+        expect(checkSvg).toHaveClass('text-gray-400', 'stroke-4');
+      });
+
+      it('applies checked styles when clicked', () => {
+        renderCheckIcon({ variant: 'outline' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+
+        fireEvent.click(checkIcon);
+
+        expect(checkIcon).toHaveClass('bg-white', 'border-3', 'border-[#079455]');
+
+        const checkSvg = checkIcon.querySelector('svg');
+        expect(checkSvg).toHaveClass('text-[#079455]', 'stroke-4');
+      });
+    });
+
+    describe('filled variant', () => {
+      it('applies filled variant styles when unchecked', () => {
+        renderCheckIcon({ variant: 'filled' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+        expect(checkIcon).toHaveClass('bg-gray-400');
+        expect(checkIcon).not.toHaveClass('border-3');
+      });
+
+      it('shows check icon with correct styles when unchecked', () => {
+        renderCheckIcon({ variant: 'filled' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+        const checkSvg = checkIcon.querySelector('svg');
+
+        expect(checkSvg).toBeInTheDocument();
+        expect(checkSvg).toHaveClass('text-white', 'stroke-4');
+      });
+
+      it('applies checked styles when clicked', () => {
+        renderCheckIcon({ variant: 'filled' });
+
+        const checkIcon = screen.getByTestId('check-icon');
+
+        fireEvent.click(checkIcon);
+
+        expect(checkIcon).toHaveClass('bg-[#079455]', 'border-[#079455]');
+
+        const checkSvg = checkIcon.querySelector('svg');
+        expect(checkSvg).toHaveClass('text-white', 'stroke-4');
+      });
+    });
+  });
+
+  describe('Toggle Behavior', () => {
+    it('starts in unchecked state', () => {
+      renderCheckIcon({ variant: 'outline' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveClass('bg-white', 'border-gray-400');
+
+      const checkSvg = checkIcon.querySelector('svg');
+      expect(checkSvg).toHaveClass('text-gray-400');
+    });
+
+    it('toggles to checked state when clicked', () => {
+      renderCheckIcon({ variant: 'outline' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+
+      expect(checkIcon).toHaveClass('border-gray-400');
+      expect(checkIcon.querySelector('svg')).toHaveClass('text-gray-400');
+
+      fireEvent.click(checkIcon);
+
+      expect(checkIcon).toHaveClass('border-[#079455]');
+      expect(checkIcon.querySelector('svg')).toHaveClass('text-[#079455]');
+    });
+
+    it('toggles back to unchecked when clicked twice', () => {
+      renderCheckIcon({ variant: 'outline' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+
+      fireEvent.click(checkIcon);
+      expect(checkIcon).toHaveClass('border-[#079455]');
+
+      fireEvent.click(checkIcon);
+      expect(checkIcon).toHaveClass('border-gray-400');
+      expect(checkIcon.querySelector('svg')).toHaveClass('text-gray-400');
+    });
+
+    it('toggles multiple times correctly', () => {
+      renderCheckIcon({ variant: 'filled' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+
+      expect(checkIcon).toHaveClass('bg-gray-400');
+
+      fireEvent.click(checkIcon);
+      expect(checkIcon).toHaveClass('bg-[#079455]');
+
+      fireEvent.click(checkIcon);
+      expect(checkIcon).toHaveClass('bg-gray-400');
+
+      fireEvent.click(checkIcon);
+      expect(checkIcon).toHaveClass('bg-[#079455]');
+    });
+  });
+
+  describe('Icon Size Mapping', () => {
+    it.each([
+      [ 'xs', 'size-3' ],
+      [ 'sm', 'size-4' ],
+      [ 'md', 'size-4' ],
+      [ 'lg', 'size-5' ],
+    ] as const)('applies correct icon size class for %s button size', (size, expectedIconClass) => {
+      renderCheckIcon({ size });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      const checkSvg = checkIcon.querySelector('svg');
+
+      expect(checkSvg).toHaveClass(expectedIconClass);
+    });
+  });
+
+  describe('RenderCondition Logic', () => {
+    it('renders check icon for outline variant', () => {
+      renderCheckIcon({ variant: 'outline' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      const checkSvg = checkIcon.querySelector('svg');
+
+      expect(checkSvg).toBeInTheDocument();
+    });
+
+    it('renders check icon for filled variant', () => {
+      renderCheckIcon({ variant: 'filled' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+      const checkSvg = checkIcon.querySelector('svg');
+
+      expect(checkSvg).toBeInTheDocument();
+    });
+
+    it('always renders exactly one check icon regardless of variant', () => {
+      const { rerender } = render(<CheckIcon variant="outline" data-testid="check-icon" />);
+
+      let checkIcon = screen.getByTestId('check-icon');
+      let checkSvgs = checkIcon.querySelectorAll('svg');
+      expect(checkSvgs).toHaveLength(1);
+
+      rerender(<CheckIcon variant="filled" data-testid="check-icon" />);
+
+      checkIcon = screen.getByTestId('check-icon');
+      checkSvgs = checkIcon.querySelectorAll('svg');
+      expect(checkSvgs).toHaveLength(1);
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('is focusable', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      checkIcon.focus();
+
+      expect(checkIcon).toHaveFocus();
+    });
+
+    it('can be activated with keyboard', () => {
+      renderCheckIcon({ variant: 'outline' });
+
+      const checkIcon = screen.getByTestId('check-icon');
+
+      expect(checkIcon).toHaveClass('border-gray-400');
+
+      fireEvent.keyDown(checkIcon, { key: 'Enter', code: 'Enter' });
+
+      expect(checkIcon).toHaveClass('border-gray-400');
+    });
+
+    it('has button role implicitly', () => {
+      renderCheckIcon();
+
+      const checkIcon = screen.getByTestId('check-icon');
+      expect(checkIcon).toHaveAttribute('type', 'button');
+    });
+  });
+});

package/src/components/atoms/CheckIcon/check-icon.tsx

@@ -0,0 +1,141 @@
+import { useEffect } from 'react';
+
+import { Check } from 'lucide-react';
+
+import { RenderCondition } from '../RenderCondition';
+
+import { useOnToggle } from '@/hooks';
+import { cn } from '@/utils';
+
+const BUTTON_SIZE = {
+  xs: 'size-5',
+  sm: 'size-6',
+  md: 'size-7',
+  lg: 'size-8',
+};
+
+const ICON_SIZE = {
+  xs: 'size-3',
+  sm: 'size-4',
+  md: 'size-4',
+  lg: 'size-5',
+};
+
+const BORDER_SIZE = {
+  xs: 'border-2',
+  sm: 'border-2',
+  md: 'border-3',
+  lg: 'border-3',
+};
+
+const DEFAULT_BG = {
+  outline: 'bg-white',
+  filled: 'bg-gray-400',
+};
+
+const CHECKED_BG = {
+  outline: 'bg-white',
+  filled: 'bg-[#079455]',
+};
+
+const DEFAULT_TEXT = {
+  outline: 'text-gray-400',
+  filled: 'text-white',
+};
+
+const CHECKED_TEXT = {
+  outline: 'text-[#079455]',
+  filled: 'text-white',
+};
+
+interface CheckIconProps {
+  className?: string;
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  variant?: 'outline' | 'filled';
+  /**
+   * Controls the checked state externally (controlled mode).
+   * When provided, the component becomes controlled and you must handle state changes via onCheckedChange.
+   */
+  checked?: boolean;
+  /**
+   * Default checked state for uncontrolled mode.
+   * Only used when 'checked' prop is not provided.
+   */
+  defaultChecked?: boolean;
+  /**
+   * Callback fired when the checked state changes.
+   * In controlled mode: you must update the 'checked' prop based on this callback.
+   * In uncontrolled mode: optional callback to listen to state changes.
+   */
+  onCheckedChange?: (checked: boolean) => void;
+  /**
+   * When true, the component becomes disabled and non-interactive.
+   */
+  disabled?: boolean;
+}
+
+function CheckIcon ({
+  className,
+  size = 'md',
+  variant = 'outline',
+  checked,
+  defaultChecked = false,
+  onCheckedChange,
+  disabled = false,
+}: CheckIconProps) {
+  const isControlled = checked !== undefined;
+
+  const { state: internalChecked, setValue: setInternalChecked } = useOnToggle(defaultChecked);
+
+  const isChecked = isControlled ? checked : internalChecked;
+
+  useEffect(() => {
+    if (isControlled && checked !== internalChecked) {
+      setInternalChecked(checked);
+    }
+  }, [ checked, internalChecked, setInternalChecked, isControlled ]);
+
+  const handleToggle = () => {
+    if (disabled) return;
+
+    const newCheckedState = !isChecked;
+
+    if (!isControlled) {
+      setInternalChecked(newCheckedState);
+    }
+
+    onCheckedChange?.(newCheckedState);
+  };
+
+  return (
+    <button
+      data-testid="check-icon"
+      type="button"
+      onClick={handleToggle}
+      disabled={disabled}
+      aria-checked={isChecked}
+      role="checkbox"
+      className={
+        cn(
+          'cursor-pointer rounded-full flex items-center justify-center transition-colors duration-200',
+          className,
+          BUTTON_SIZE[size],
+          isChecked ? CHECKED_BG[variant] : DEFAULT_BG[variant],
+          variant === 'outline' && BORDER_SIZE[size],
+          isChecked ? 'border-[#079455]' : 'border-gray-400',
+          disabled && !isChecked && 'cursor-default opacity-50'
+        )
+      }
+    >
+      <RenderCondition condition={variant === 'outline'}>
+        <Check className={cn(ICON_SIZE[size], isChecked ? CHECKED_TEXT[variant] : DEFAULT_TEXT[variant], 'stroke-4')} />
+      </RenderCondition>
+      <RenderCondition condition={variant === 'filled'}>
+        <Check className={cn(ICON_SIZE[size], isChecked ? CHECKED_TEXT[variant] : DEFAULT_TEXT[variant], 'stroke-4')} />
+      </RenderCondition>
+    </button>
+  );
+}
+
+export type { CheckIconProps };
+export { CheckIcon };

package/src/components/atoms/CheckIcon/index.ts

@@ -0,0 +1 @@
+export { CheckIcon } from './check-icon';

package/src/components/atoms/Checkbox/checkbox.stories.tsx

@@ -0,0 +1,133 @@
+import * as React from 'react';
+
+import { Checkbox } from './checkbox';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Components/Data Entry/Checkbox',
+  component: Checkbox,
+  tags: [ 'autodocs' ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A control that allows the user to toggle between checked and not checked.',
+      },
+    },
+    controls: { expanded: true },
+  },
+  argTypes: {
+    className: {
+      control: 'text',
+      description: 'Additional Tailwind classes for visual customization.',
+      table: {
+        category: 'Style',
+        type: { summary: 'string' },
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the checkbox.',
+      table: {
+        category: 'Behavior',
+        type: { summary: 'boolean' },
+      },
+    },
+    defaultChecked: {
+      control: 'boolean',
+      description: 'Defines if the checkbox will be checked initially.',
+      table: {
+        category: 'State',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    required: {
+      control: 'boolean',
+      description: 'Defines if the field is required (for use in forms).',
+      table: {
+        category: 'Validation',
+        type: { summary: 'boolean' },
+      },
+    },
+    onCheckedChange: {
+      action: 'checkedChange',
+      description: 'Callback when the checkbox state changes.',
+      table: {
+        category: 'Events',
+        type: { summary: '(checked: boolean) => void' },
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Checked: Story = {
+  args: {
+    defaultChecked: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Checkbox with initial checked state.',
+      },
+    },
+  },
+};
+
+export const Default: Story = {
+  args: {
+    defaultChecked: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default unchecked checkbox by default.',
+      },
+    },
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Disabled checkbox with no interactions possible.',
+      },
+    },
+  },
+};
+
+export const WithLabel: Story = {
+  render: args => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [ checked, setChecked ] = React.useState(false);
+
+    return (
+      <div className="flex items-center space-x-2">
+        <Checkbox
+          {...args}
+          id="terms"
+          checked={checked}
+          onCheckedChange={val => setChecked(Boolean(val))}
+        />
+        <label htmlFor="terms" className="flex items-center space-x-2">
+          {checked ? 'Selected' : 'Not selected'}
+        </label>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example with a label that reflects the checkbox state dynamically.',
+      },
+    },
+  },
+};

package/src/components/atoms/Checkbox/checkbox.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect } from 'vitest';
+
+import { Checkbox } from './checkbox';
+
+describe('<Checkbox />', () => {
+  it('should render the checkbox component', () => {
+    render(<Checkbox aria-label="Accept terms" />);
+    const checkbox = screen.getByRole('checkbox', { name: /accept terms/i });
+    expect(checkbox).toBeInTheDocument();
+  });
+
+  it('should be unchecked by default', () => {
+    render(<Checkbox aria-label="Subscribe" />);
+    const checkbox = screen.getByRole('checkbox', { name: /subscribe/i });
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it('should toggle checked state when clicked', async () => {
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Enable notifications" />);
+    const checkbox = screen.getByRole('checkbox', { name: /enable notifications/i });
+
+    await user.click(checkbox);
+    expect(checkbox).toBeChecked();
+
+    await user.click(checkbox);
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it('should be focusable and toggle with keyboard (space)', async () => {
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Keyboard accessible" />);
+    const checkbox = screen.getByRole('checkbox', { name: /keyboard accessible/i });
+
+    checkbox.focus();
+    expect(checkbox).toHaveFocus();
+
+    await user.keyboard('[Space]');
+    expect(checkbox).toBeChecked();
+
+    await user.keyboard('[Space]');
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it('should not be clickable when disabled', async () => {
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Disabled checkbox" disabled />);
+    const checkbox = screen.getByRole('checkbox', { name: /disabled checkbox/i });
+
+    expect(checkbox).toBeDisabled();
+    expect(checkbox).not.toBeChecked();
+
+    await user.click(checkbox);
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it('should have proper accessibility attributes when invalid', () => {
+    render(<Checkbox aria-label="Required checkbox" aria-invalid="true" />);
+    const checkbox = screen.getByRole('checkbox', { name: /required checkbox/i });
+
+    expect(checkbox).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('should match snapshot', () => {
+    const { container } = render(<Checkbox aria-label="Snapshot test" />);
+    expect(container).toMatchSnapshot();
+  });
+});

package/src/components/atoms/Checkbox/checkbox.tsx

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import { CheckIcon } from 'lucide-react';
+
+import { cn } from '@/utils';
+
+function Checkbox ({
+  className,
+  ...props
+}: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        'cursor-pointer border-input data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground dark:data-[state=checked]:bg-primary data-[state=checked]:border-primary focus-visible-primary aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive size-4 shrink-0 rounded-[4px] border shadow-xs transition-shadow outline-none disabled:cursor-not-allowed disabled:opacity-50',
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="flex items-center justify-center text-current transition-none"
+      >
+        <CheckIcon className="size-3 stroke-4" />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}
+
+export { Checkbox };

package/src/components/atoms/Checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox } from './checkbox';

package/src/components/atoms/Flex/flex.stories.tsx

@@ -0,0 +1,33 @@
+import { Flex } from './flex';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof Flex> = {
+  title: 'Components/Layout/Flex',
+  component: Flex,
+  tags: [ 'autodocs' ],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Flex is a layout component that displays its children in a row direction.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Flex>;
+
+export const Default: Story = {
+  args: {
+    className: 'gap-4 p-4 bg-gray-100',
+    children: (
+      <>
+        <div className="w-10 h-10 bg-red-500" />
+        <div className="w-10 h-10 bg-green-500" />
+        <div className="w-10 h-10 bg-blue-500" />
+      </>
+    ),
+  },
+};