@brcarddev/frontend-commons 1.0.2

package/src/components/organisms/Form/form.stories.tsx

@@ -0,0 +1,155 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { useForm } from 'react-hook-form';
+
+import {
+  Form,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+  FormField,
+} from './form';
+
+import { Input, Button, Card, CardContent, CardHeader, CardTitle } from '@/components';
+
+interface ExampleFormValues {
+  email: string;
+  password: string;
+}
+
+const meta: Meta<typeof Form> = {
+  title: 'Components/Data Entry/Form',
+  component: Form,
+  tags: [ 'autodocs' ],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+**Forms are hard.**  
+They’re one of the most common things you build in a web application — but also one of the most complex.
+
+### Well-designed HTML forms should be:
+- Well-structured and semantically correct.
+- Easy to use and keyboard-navigable.
+- Accessible using appropriate ARIA attributes and labels.
+- Support both client-side and server-side validation.
+- Well-styled and consistent with the rest of the application.
+
+### In this guide, we’ll see how to build forms using \`react-hook-form\` and \`zod\`:
+We'll use a \`<FormField>\` component to compose accessible forms using Radix UI components.
+
+### Features:
+- The \`<Form />\` component is a wrapper around the \`react-hook-form\` library.
+- Composable components for building forms.
+- A \`<FormField />\` component for controlled form fields.
+- Schema validation using \`zod\`.
+- Handles accessibility and error messages.
+- Uses \`React.useId()\` to generate unique IDs.
+- Applies correct \`aria\` attributes based on state.
+- Built to work with all Radix UI components.
+- Bring your own schema library — we use \`zod\`, but you can use anything.
+- Full control over markup and styling.
+
+### Anatomy
+
+\`\`\`tsx
+<Form methods={...} onValid={...}>
+  <FormField
+    control={...}
+    name="..."
+    render={() => (
+      <FormItem>
+        <FormLabel />
+        <FormControl>
+          { /* Your form field */ }
+        </FormControl>
+        <FormDescription />
+        <FormMessage />
+      </FormItem>
+    )}
+  />
+</Form>
+\`\`\`
+
+### Example
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Form>;
+
+export const Template: Story = {
+  name: 'Form with validation',
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const form = useForm<ExampleFormValues>({
+      defaultValues: {
+        email: '',
+        password: '',
+      },
+    });
+
+    const onSubmit = (data: ExampleFormValues) => {
+      alert(JSON.stringify(data, null, 2));
+    };
+
+    return (
+      <Card className="w-full max-w-md">
+        <CardHeader>
+          <CardTitle>Example of Form</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <Form methods={form} onValid={onSubmit}>
+            <div className="grid gap-4">
+              <FormField
+                control={form.control}
+                name="email"
+                rules={{ required: 'Email is required' }}
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel required helpText="You will receive notifications at this email.">Email</FormLabel>
+                    <FormControl>
+                      <Input placeholder="example@email.com" {...field} />
+                    </FormControl>
+                    <FormDescription>
+                      You will receive notifications at this email.
+                    </FormDescription>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+              <FormField
+                control={form.control}
+                name="password"
+                rules={{
+                  required: 'Password is required',
+                  minLength: {
+                    value: 6,
+                    message: 'Minimum of 6 characters',
+                  },
+                }}
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>Password</FormLabel>
+                    <FormControl>
+                      <Input type="password" placeholder="******" {...field} />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+              <Button type="submit">Login</Button>
+            </div>
+          </Form>
+        </CardContent>
+      </Card>
+    );
+  },
+};

package/src/components/organisms/Form/form.test.tsx

@@ -0,0 +1,49 @@
+import { composeStories } from '@storybook/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import * as stories from './form.stories';
+
+const { Template } = composeStories(stories);
+
+describe('<Form />', () => {
+  it('renders form elements correctly', () => {
+    render(<Template />);
+
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    expect(screen.getByPlaceholderText('******')).toBeInTheDocument();
+    expect(screen.getByText(/you will receive notifications at this email/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
+  });
+
+  it('shows validation error when submitting empty form', async () => {
+    render(<Template />);
+
+    await userEvent.click(screen.getByRole('button', { name: /login/i }));
+
+    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
+    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
+  });
+
+  it('calls onValid when form is filled and submitted', async () => {
+    window.alert = vi.fn();
+
+    render(<Template />);
+
+    await userEvent.type(screen.getByLabelText(/email/i), 'example@email.com');
+    await userEvent.type(screen.getByPlaceholderText('******'), '123123');
+
+    await userEvent.click(screen.getByRole('button', { name: /login/i }));
+
+    expect(window.alert).toHaveBeenCalledOnce();
+    expect(window.alert).toHaveBeenCalledWith(
+      JSON.stringify({ email: 'example@email.com', password: '123123' }, null, 2)
+    );
+  });
+
+  it('should match snapshot', () => {
+    const { container } = render(<Template />);
+    expect(container).toMatchSnapshot();
+  });
+});

package/src/components/organisms/Form/form.tsx

@@ -0,0 +1,133 @@
+import * as React from 'react';
+
+import * as LabelPrimitive from '@radix-ui/react-label';
+import { Slot } from '@radix-ui/react-slot';
+import {
+  Controller,
+  FormProvider,
+  SubmitErrorHandler,
+  SubmitHandler,
+  UseFormReturn,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+} from 'react-hook-form';
+
+import { Label } from '@/components';
+import { FormFieldContext, FormItemContext, useFormField } from '@/hooks';
+import { cn } from '@/utils';
+
+interface FormProps<T extends FieldValues = FieldValues>
+  extends Omit<React.ComponentProps<'form'>, 'onSubmit' | 'onInvalid'> {
+  methods: UseFormReturn<T>;
+  onValid: SubmitHandler<T>;
+  onInvalid?: SubmitErrorHandler<T>;
+}
+
+function Form<T extends FieldValues>({ methods, onValid, onInvalid, className, children, ...props }: FormProps<T>) {
+  return (
+    <FormProvider {...methods} data-testid="form-provider">
+      <form
+        onSubmit={methods.handleSubmit(onValid, onInvalid)}
+        className={cn('w-full', className)}
+        data-testid="form"
+        {...props}
+      >
+        {children}
+      </form>
+    </FormProvider>
+  );
+}
+
+const FormField = <
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+    ...props
+  }: ControllerProps<TFieldValues, TName>) => {
+  return (
+    <FormFieldContext.Provider value={{ name: props.name }}>
+      <Controller {...props} />
+    </FormFieldContext.Provider>
+  );
+};
+
+function FormItem({ className, ...props }: React.ComponentProps<'div'>) {
+  const id = React.useId();
+
+  return (
+    <FormItemContext.Provider value={{ id }}>
+      <div data-slot="form-item" data-testid="form-item" className={cn('flex flex-col gap-1.5', className)} {...props} />
+    </FormItemContext.Provider>
+  );
+}
+
+function FormLabel({ className, required = false, helpText, ...props }:
+  React.ComponentProps<typeof LabelPrimitive.Root> & { required?: boolean, helpText?: string })
+{
+  const { error, formItemId } = useFormField();
+
+  return (
+    <Label
+      data-slot="form-label"
+      error={!!error}
+      className={className}
+      htmlFor={formItemId}
+      required={required}
+      helpText={helpText}
+      {...props}
+    />
+
+  );
+}
+
+function FormControl({ ...props }: React.ComponentProps<typeof Slot>) {
+  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
+
+  return (
+    <Slot
+      data-slot="form-control"
+      id={formItemId}
+      aria-describedby={!error ? `${formDescriptionId}` : `${formDescriptionId} ${formMessageId}`}
+      aria-invalid={!!error}
+      {...props}
+    />
+  );
+}
+
+function FormDescription({ className, ...props }: React.ComponentProps<'p'>) {
+  const { formDescriptionId } = useFormField();
+
+  return (
+    <p
+      data-slot="form-description"
+      id={formDescriptionId}
+      className={cn('text-gray-600 text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+function FormMessage({ className, ...props }: React.ComponentProps<'p'>) {
+  const { error, formMessageId } = useFormField();
+  const body = error ? String(error?.message ?? '') : props.children;
+
+  if (!body) {
+    return null;
+  }
+
+  return (
+    <p
+      data-testid="form-message"
+      data-slot="form-message"
+      id={formMessageId}
+      className={cn('text-error-500 text-sm', className)}
+      {...props}
+    >
+      {body}
+    </p>
+  );
+}
+
+export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage };
+

package/src/components/organisms/Form/index.ts

@@ -0,0 +1 @@
+export * from './form';

package/src/components/organisms/Sidebar/index.ts

@@ -0,0 +1 @@
+export * from './sidebar';

package/src/components/organisms/Sidebar/sidebar.stories.tsx

@@ -0,0 +1,86 @@
+import { LucideHome, LucideSettings } from 'lucide-react';
+
+import {
+  SidebarProvider,
+  Sidebar,
+  SidebarTrigger,
+  SidebarInset,
+  SidebarHeader,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarSeparator,
+  SidebarInput,
+} from './sidebar';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '@/components';
+
+const meta: Meta<typeof Sidebar> = {
+  title: 'Components/Navigation/Sidebar',
+  component: Sidebar,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Sidebar with navigation menu, with support for themes and custom styles.',
+      },
+    },
+  },
+  tags: [ 'autodocs' ],
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const BasicSidebar: Story = {
+  render: () => (
+    <SidebarProvider>
+      <SidebarTrigger className="m-2" />
+      <div className="flex">
+        <Sidebar>
+          <SidebarHeader>
+            <SidebarInput placeholder="Buscar..." />
+          </SidebarHeader>
+
+          <SidebarContent>
+            <SidebarGroup>
+              <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <Button variant="ghost" className="w-full justify-start">
+                      <LucideHome className="mr-2 h-4 w-4" /> Home
+                    </Button>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <Button variant="ghost" className="w-full justify-start">
+                      <LucideSettings className="mr-2 h-4 w-4" /> Settings
+                    </Button>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+
+            <SidebarSeparator />
+
+            <SidebarFooter>
+              <p className="text-sm text-muted-foreground">© 2025 My Company</p>
+            </SidebarFooter>
+          </SidebarContent>
+        </Sidebar>
+
+        <SidebarInset className="p-4">
+          <h1 className="text-2xl font-bold">Main Content</h1>
+          <p>This is the main content of the application.</p>
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  ),
+};

package/src/components/organisms/Sidebar/sidebar.test.tsx

@@ -0,0 +1,101 @@
+import { composeStories } from '@storybook/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Sidebar, SidebarProvider, SidebarRail, SidebarTrigger } from './sidebar';
+import * as stories from './sidebar.stories';
+
+const { BasicSidebar } = composeStories(stories);
+
+const renderSidebar = () => render(<BasicSidebar />);
+
+describe('<Sidebar />', () => {
+  it('renders children inside SidebarProvider', async () => {
+    renderSidebar();
+
+    expect(screen.getByTestId('sidebar-content')).toBeInTheDocument();
+  });
+
+  it('uses the default open value when not controlled', async () => {
+    render(
+      <SidebarProvider>
+        <Sidebar side="left" variant="sidebar">
+          <div>Sidebar Content</div>
+        </Sidebar>
+      </SidebarProvider>
+    );
+    expect(screen.getByText(/sidebar content/i)).toBeInTheDocument();
+  });
+
+  it('respects controlled open value and triggers callback', async () => {
+    const onOpenChange = vi.fn();
+    render(
+      <SidebarProvider open={false} onOpenChange={onOpenChange}>
+        <SidebarTrigger />
+      </SidebarProvider>
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: /toggle sidebar/i }));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it('sets a cookie when toggling sidebar', async () => {
+    const setCookieSpy = vi.spyOn(document, 'cookie', 'set');
+    render(
+      <SidebarProvider>
+        <SidebarTrigger />
+      </SidebarProvider>
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: /toggle sidebar/i }));
+    expect(setCookieSpy).toHaveBeenCalled();
+  });
+
+  it('toggles sidebar with keyboard shortcut (ctrl+b)', async () => {
+    render(
+      <SidebarProvider>
+        <Sidebar side="left">
+          <div>Sidebar Content</div>
+        </Sidebar>
+      </SidebarProvider>
+    );
+
+    fireEvent.keyDown(window, {
+      key: 'b',
+      ctrlKey: true,
+    });
+
+    const sidebar = screen.getByTestId('sidebar-wrapper');
+    expect(sidebar).toBeInTheDocument();
+  });
+
+  it('renders SidebarTrigger and calls toggleSidebar', async () => {
+    render(
+      <SidebarProvider>
+        <SidebarTrigger />
+      </SidebarProvider>
+    );
+
+    const button = screen.getByRole('button', { name: /toggle sidebar/i });
+    expect(button).toBeInTheDocument();
+    await userEvent.click(button);
+  });
+
+  it('renders SidebarRail and toggles sidebar on click', async () => {
+    render(
+      <SidebarProvider>
+        <SidebarRail />
+      </SidebarProvider>
+    );
+
+    const rail = screen.getByRole('button', { name: /toggle sidebar/i });
+    await userEvent.click(rail);
+    expect(rail).toBeInTheDocument();
+  });
+
+  it('should match snapshot', () => {
+    const { container } = renderSidebar();
+    expect(container).toMatchSnapshot();
+  });
+});