### Development Setup and Scripts

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Instructions for setting up the development environment and common scripts for building, testing, and formatting the component library and documentation site.

```bash
git clone https://github.com/your-username/components.git
cd components
pnpm install
pnpm dev
pnpm build
pnpm --filter ./packages/lib test
pnpm --filter ./packages/lib test:watch
pnpm format
```

--------------------------------

### Add Live Component Examples

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

This code demonstrates how to create live examples for a component, allowing users to see different variations and states. It's written in React and TypeScript.

```tsx
import { MyComponent } from "@g4rcez/components/my-component";

export const MyComponentExample = () => {
  return (
    <div className="space-y-4">
      <MyComponent variant="default">Default</MyComponent>
      <MyComponent variant="primary">Primary</MyComponent>
    </div>
  );
};
```

--------------------------------

### Development Setup and Scripts

Source: https://github.com/g4rcez/components/blob/main/README.md

Instructions for setting up the development environment, including cloning the repository, installing dependencies with pnpm, and running development or build scripts.

```bash
# Clone the repository
git clone https://github.com/g4rcez/components.git
cd components

# Install dependencies
pnpm install

# Start development server (docs site)
pnpm dev

# Build the library
pnpm build
```

--------------------------------

### Install Tailwind CSS v4 and @g4rcez/components

Source: https://github.com/g4rcez/components/blob/main/docs/TAILWIND_V4_INTEGRATION.md

Installs the necessary packages for Tailwind CSS v4 and the @g4rcez/components library using npm.

```bash
# Install Tailwind CSS v4 (when available)
npm install tailwindcss@next

# Install the components library
npm install @g4rcez/components
```

--------------------------------

### Branching Strategy for Contributions

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Provides examples of Git commands for creating feature, bug fix, and documentation branches according to the project's workflow.

```bash
git checkout -b feature/component-name
git checkout -b fix/issue-description
git checkout -b docs/update-readme
```

--------------------------------

### Install G4rcez Components

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Installs the G4rcez components library using npm.

```bash
npm install @g4rcez/components
```

--------------------------------

### Basic Setup with ComponentsProvider

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Demonstrates the basic setup for using G4rcez components by wrapping the application with ComponentsProvider and importing the necessary CSS.

```tsx
import { ComponentsProvider } from "@g4rcez/components";
import "@g4rcez/components/index.css";

function App() {
  return (
    <ComponentsProvider>
      <YourApp />
    </ComponentsProvider>
  );
}
```

--------------------------------

### Global CSS Setup with Tailwind and @g4rcez/components

Source: https://github.com/g4rcez/components/blob/main/docs/TAILWIND_V4_INTEGRATION.md

Sets up global CSS by importing Tailwind CSS and @g4rcez/components, and defines custom CSS variables for theming and animations.

```css
/* styles/globals.css */
@import "tailwindcss";
@import "@g4rcez/components/index.css";

/* Custom CSS variables for theming */
@theme {
  --color-brand-primary: #3b82f6;
  --color-brand-secondary: #64748b;
  --color-brand-accent: #8b5cf6;

  --spacing-component: 1rem;
  --radius-component: 0.5rem;

  --shadow-component: 0 4px 6px -1px rgb(0 0 0 / 0.1);
}

/* Custom animations */
@keyframes slideInRight {
  from {
    transform: translateX(100%);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes pulse-soft {
  0%,
  100% {
    opacity: 1;
  }
  50% {
    opacity: 0.8;
  }
}
```

--------------------------------

### Add Component Documentation Page

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

This snippet shows how to create a documentation page for a component using React and TypeScript. It includes importing the component, displaying its description, and providing an example usage.

```tsx
import { MyComponent } from "@g4rcez/components/my-component";

export default function MyComponentPage() {
  return (
    <div>
      <h1>MyComponent</h1>
      <p>Component description...</p>

      <h2>Examples</h2>
      <MyComponent variant="primary">Example usage</MyComponent>

      <h2>API Reference</h2>
      {/* Props table */}
    </div>
  );
}
```

--------------------------------

### Write Component Tests

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Provides examples of unit tests for a React component using Vitest and React Testing Library. Covers rendering, prop variations, and ref forwarding.

```tsx
// packages/lib/tests/components/my-component.test.tsx
import { render, screen } from "@testing-library/react";
import { MyComponent } from "../../src/components/category/my-component";

describe("MyComponent", () => {
  it("renders with default props", () => {
    render(<MyComponent>Test content</MyComponent>);
    expect(screen.getByText("Test content")).toBeInTheDocument();
  });

  it("applies variant classes correctly", () => {
    render(<MyComponent variant="primary">Test</MyComponent>);
    const element = screen.getByText("Test");
    expect(element).toHaveClass("primary-classes");
  });

  it("forwards ref correctly", () => {
    const ref = React.createRef<HTMLDivElement>();
    render(<MyComponent ref={ref}>Test</MyComponent>);
    expect(ref.current).toBeInstanceOf(HTMLDivElement);
  });
});

```

--------------------------------

### Example: Basic Card

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

A simple example demonstrating a Card component with a heading and paragraph content.

```tsx
<Card>
  <h3>Welcome</h3>
  <p>This is a simple card with basic content.</p>
</Card>
```

--------------------------------

### Create a New React Component

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Demonstrates the creation of a new React component using TypeScript, CVA for styling variants, and forwardRef for ref forwarding. Includes prop definitions, JSDoc comments, and usage examples.

```tsx
// packages/lib/src/components/category/my-component.tsx
import React, { forwardRef } from "react";
import { cva } from "class-variance-authority";
import { css } from "../../lib/dom";

/**
 * Component variant definitions
 * @internal
 */
const variants = {
  variant: {
    default: "default-classes",
    primary: "primary-classes",
  },
  size: {
    sm: "small-classes",
    md: "medium-classes",
  },
};

/**
 * Class variance authority configuration
 * @internal
 */
const componentVariants = cva("base-classes", {
  variants,
  defaultVariants: { variant: "default", size: "md" },
});

/**
 * Props for the MyComponent
 */
export interface MyComponentProps {
  /** Component variant */
  variant?: keyof typeof variants.variant;
  /** Component size */
  size?: keyof typeof variants.size;
  /** Additional CSS classes */
  className?: string;
  /** Component children */
  children?: React.ReactNode;
}

/**
 * A description of what this component does.
 *
 * @example
 * ```tsx
 * <MyComponent variant="primary" size="lg">
 *   Content
 * </MyComponent>
 * ```
 */
export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
  ({ variant, size, className, children, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={css(componentVariants({ variant, size }), className)}
        data-component="my-component"
        {...props}
      >
        {children}
      </div>
    );
  },
);

MyComponent.displayName = "MyComponent";

```

--------------------------------

### Currency Input Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Example of using the Input component with a currency mask and state management.

```tsx
<Input
  mask="currency"
  currency="USD"
  locale="en-US"
  placeholder="Amount"
  value={amount}
  onChange={(e) => setAmount(e.target.value)}
/>
```

--------------------------------

### Basic Text Input Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

A standard example of using the Input component for text input with state management.

```tsx
<Input
  placeholder="Enter your name"
  value={name}
  onChange={(e) => setName(e.target.value)}
/>
```

--------------------------------

### Installation

Source: https://github.com/g4rcez/components/blob/main/README.md

Provides instructions for installing the @g4rcez/components library using npm, yarn, or pnpm package managers.

```bash
npm install @g4rcez/components
# or
yarn add @g4rcez/components
# or
pnpm add @g4rcez/components
```

--------------------------------

### Project Structure Overview

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Illustrates the directory structure of the @g4rcez/components project, highlighting the main library ('lib') and documentation ('docs') packages.

```directory-structure
packages/
├── lib/                          # Main component library
│   ├── src/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── lib/
│   │   ├── styles/
│   │   └── config/
│   ├── tests/
│   └── dist/
└── docs/                        # Documentation site
    ├── src/app/docs/
    └── src/components/examples/
```

--------------------------------

### Basic Dialog Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Modal.md

A complete example demonstrating how to use the Modal component as a basic dialog, including a button to open it and confirmation/cancel actions within the footer.

```tsx
const BasicDialog = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>

      <Modal open={open} onChange={setOpen} title="Confirm Action">
        <p>Are you sure you want to proceed?</p>
        <div className="flex gap-2 mt-4">
          <button
            onClick={() => setOpen(false)}
            className="px-4 py-2 bg-gray-200 rounded"
          >
            Cancel
          </button>
          <button
            onClick={() => setOpen(false)}
            className="px-4 py-2 bg-red-500 text-white rounded"
          >
            Confirm
          </button>
        </div>
      </Modal>
    </>
  );
};

```

--------------------------------

### Tailwind CSS v4 Integration Examples

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Showcases examples of Tailwind CSS v4 features integrated into various project components. Demonstrates CSS variables, container queries, CSS Grid areas, color functions, modern animations, and responsive design patterns.

```APIDOC
Component Examples with Tailwind CSS v4:

Button:
  Features: CSS variables, container queries, dynamic styling, custom animations

Input:
  Features: Responsive forms, locale-aware styling, validation animations, multi-step layouts

Modal:
  Features: Dynamic theming, container-based sizing, CSS Grid areas, modern animations

Card:
  Features: Masonry layouts, hover effects, data visualization, adaptive components

Alert:
  Features: Notification systems, progress indicators, stacking animations

Tabs:
  Features: Vertical layouts, CSS Grid areas, animated transitions, responsive behavior

Select:
  Features: Dynamic theming, responsive forms, advanced state styling

Checkbox:
  Features: Task lists, priority styling, animated states, complex layouts
```

--------------------------------

### Alert Basic Variants Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Alert.md

Shows examples of using the Alert component with different themes like 'info', 'success', 'warn', and 'danger'.

```tsx
<Alert theme="info" title="Information">
  This is an informational message.
</Alert>

<Alert theme="success" title="Success!">
  Your changes have been saved successfully.
</Alert>

<Alert theme="warn" title="Warning">
  Please review your input before proceeding.
</Alert>

<Alert theme="danger" title="Error">
  Something went wrong. Please try again.
</Alert>
```

--------------------------------

### Date Input Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Example of using the Input component with a date mask and state management.

```tsx
<Input
  mask="99/99/9999"
  placeholder="MM/DD/YYYY"
  value={date}
  onChange={(e) => setDate(e.target.value)}
/>
```

--------------------------------

### Example: Basic Tabs

Source: https://github.com/g4rcez/components/blob/main/docs/components/Tabs.md

A functional example of the Tabs component, demonstrating how to manage the active tab state and render different content for each tab.

```tsx
const BasicTabs = () => {
  const [active, setActive] = useState("overview");

  return (
    <Tabs active={active} onChange={setActive}>
      <Tab id="overview" title="Overview">
        <h3>Project Overview</h3>
        <p>This is the overview of your project.</p>
      </Tab>

      <Tab id="details" title="Details">
        <h3>Project Details</h3>
        <p>Detailed information about your project.</p>
      </Tab>

      <Tab id="settings" title="Settings">
        <h3>Project Settings</h3>
        <p>Configure your project settings here.</p>
      </Tab>
    </Tabs>
  );
};
```

--------------------------------

### Credit Card Input Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Example of using the Input component with a credit card mask and state management.

```tsx
<Input
  mask="9999 9999 9999 9999"
  placeholder="Card number"
  value={cardNumber}
  onChange={(e) => setCardNumber(e.target.value)}
/>
```

--------------------------------

### Run Component Tests

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Commands to execute tests for the 'lib' package using pnpm, including running all tests, watching for changes, and generating a coverage report.

```bash
# Run all tests
pnpm --filter ./packages/lib test

# Watch mode
pnpm --filter ./packages/lib test:watch

# Coverage report
pnpm --filter ./packages/lib test --coverage

```

--------------------------------

### Percentage Mask Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Demonstrates the usage of the percentage mask for the Input component.

```tsx
<Input mask="percentage" placeholder="Enter percentage" />
```

--------------------------------

### Example: Card as Different Elements

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Demonstrates rendering the Card component as different HTML elements like 'article' or 'section' using the `as` prop.

```tsx
// As article
<Card as="article" title="Blog Post">
  <p>Blog post content...</p>
</Card>

// As section
<Card as="section" title="Features">
  <ul>
    <li>Feature 1</li>
    <li>Feature 2</li>
  </ul>
</Card>
```

--------------------------------

### Phone Number Input Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Example of using the Input component with a phone number mask and state management.

```tsx
<Input
  mask="(99) 99999-9999"
  placeholder="Phone number"
  value={phone}
  onChange={(e) => setPhone(e.target.value)}
/>
```

--------------------------------

### Basic Button Usage

Source: https://github.com/g4rcez/components/blob/main/docs/components/Button.md

Shows a simple example of how to render and use the Button component with default settings.

```tsx
<Button>Click me</Button>
```

--------------------------------

### Polymorph Basic Usage Examples

Source: https://github.com/g4rcez/components/blob/main/docs/components/Polymorph.md

Illustrates the basic usage of the Polymorph component, showing how to render it as different HTML elements like button, link, and div.

```tsx
<Polymorph as="button">Button Element</Polymorph>
<Polymorph as="a" href="/link">Link Element</Polymorph>
<Polymorph as="div">Div Element</Polymorph>
```

--------------------------------

### Basic Select Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Select.md

An example demonstrating how to manage the selected value of the Select component using React's useState hook and handle changes.

```tsx
const [selectedValue, setSelectedValue] = useState("");

<Select
  options={[
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
  ]}
  placeholder="Select a fruit"
  value={selectedValue}
  onChange={(e) => setSelectedValue(e.target.value)}
/>;
```

--------------------------------

### Modal Use Cases (React)

Source: https://github.com/g4rcez/components/blob/main/docs/components/Modal.md

Examples demonstrating various use cases for the Modal component, including confirmation dialogs, form modals for project creation, navigation drawers for menus, and mobile action sheets. Each example shows how to configure the `Modal` component with different `type` props and content.

```tsx
<Modal open={open} onChange={setOpen} title="Delete Item">
  <p>
    Are you sure you want to delete this item? This action cannot be undone.
  </p>
</Modal>
```

```tsx
<Modal open={open} onChange={setOpen} title="Create New Project">
  <ProjectForm onSubmit={handleSubmit} />
</Modal>
```

```tsx
<Modal open={open} onChange={setOpen} type="drawer" title="Menu">
  <NavigationMenu />
</Modal>
```

```tsx
<Modal open={open} onChange={setOpen} type="sheet" title="Actions">
  <ActionButtons />
</Modal>
```

--------------------------------

### Currency Mask Examples

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Illustrates how to apply currency masks to the Input component for different locales and currencies.

```tsx
// US Dollar
<Input mask="currency" currency="USD" locale="en-US" />

// Euro
<Input mask="currency" currency="EUR" locale="de-DE" />

// Brazilian Real
<Input mask="currency" currency="BRL" locale="pt-BR" />
```

--------------------------------

### Update Package Exports

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Configures the `package.json` to correctly export the component for different module systems (import, require, default).

```json
{
  "./my-component": {
    "type": "./dist/components/category/my-component.d.ts",
    "import": "./dist/components/category/my-component.js",
    "require": "./dist/components/category/my-component.js",
    "default": "./dist/components/category/my-component.js"
  }
}
```

--------------------------------

### Select Component Use Cases

Source: https://github.com/g4rcez/components/blob/main/docs/components/Select.md

Examples of using the Select component for common UI patterns like selecting user preferences (theme), status, and priority levels.

```tsx
<Select
  options={[
    { value: "light", label: "Light Theme" },
    { value: "dark", label: "Dark Theme" },
    { value: "auto", label: "Auto" },
  ]}
  placeholder="Select theme"
/>
```

```tsx
<Select
  options={[
    { value: "active", label: "Active" },
    { value: "inactive", label: "Inactive" },
    { value: "pending", label: "Pending" },
  ]}
  placeholder="Select status"
/>
```

```tsx
<Select
  options={[
    { value: "high", label: "High Priority" },
    { value: "medium", label: "Medium Priority" },
    { value: "low", label: "Low Priority" },
  ]}
  placeholder="Select priority"
/>
```

--------------------------------

### Priority Tags Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Tag.md

Shows how to implement priority tags with different themes (danger, warn, muted) and sizes (small) to indicate urgency or importance.

```tsx
<Tag theme="danger" size="small">High Priority</Tag>
<Tag theme="warn" size="small">Medium Priority</Tag>
<Tag theme="muted" size="small">Low Priority</Tag>
```

--------------------------------

### RegExp Mask Examples

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Shows how to use regular expressions to define custom input masks for the Input component.

```tsx
// Only letters
<Input mask={[/[a-zA-Z]/]} placeholder="Letters only" />

// Only numbers
<Input mask={[/d/]} placeholder="Numbers only" />

// Mixed pattern
<Input mask={[/[A-Z]/, /\d/, /\d/, "-", /[A-Z]/, /\d/, /\d/]} placeholder="A99-A99" />
```

--------------------------------

### Export Component in Index

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Shows how to export a newly created component from the library's main index file to make it available for import.

```tsx
export * from "./category/my-component";
```

--------------------------------

### Example: Card with Title

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Illustrates using the `title` prop to automatically generate a card header with user profile information.

```tsx
<Card title="User Profile">
  <div className="space-y-4">
    <div>
      <label>Name:</label>
      <p>John Doe</p>
    </div>
    <div>
      <label>Email:</label>
      <p>john@example.com</p>
    </div>
  </div>
</Card>
```

--------------------------------

### Polymorph Component Examples: With TypeScript

Source: https://github.com/g4rcez/components/blob/main/docs/components/Polymorph.md

Demonstrates TypeScript integration with Polymorph, showing how it correctly types props for button and input elements, including event handlers.

```tsx
// TypeScript knows this is a button and provides button props
<Polymorph
  as="button"
  type="submit"
  disabled={false}
  onClick={(e) => {
    // e is properly typed as MouseEvent<HTMLButtonElement>
    console.log('Button clicked');
  }}>
  Submit
</Polymorph>

// TypeScript knows this is an input and provides input props
<Polymorph
  as="input"
  type="text"
  placeholder="Enter text"
  value={value}
  onChange={(e) => {
    // e is properly typed as ChangeEvent<HTMLInputElement>
    setValue(e.target.value);
  }}/>
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/g4rcez/components/blob/main/ARCHITECTURE.md

Outlines the essential commands for local development, including starting the development server, running tests, and building the library. These commands facilitate the development and maintenance of the components.

```bash
# Start development environment
pnpm dev

# Run tests
pnpm test

# Build library
pnpm build
```

--------------------------------

### Release Versioning and Steps

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Details on the versioning strategy (Semantic Versioning) and the steps involved in releasing new versions of the component library, including version bumping, building, testing, publishing, and tagging.

```bash
# Update version in package.json
npm version patch|minor|major

pnpm build
pnpm test

npm publish

git tag v1.0.0
git push origin v1.0.0
```

--------------------------------

### Monorepo Project Structure

Source: https://github.com/g4rcez/components/blob/main/ARCHITECTURE.md

Illustrates the monorepo organization for the @g4rcez/components library, detailing the 'packages' directory with 'lib' for the main component library and 'docs' for the documentation site. It outlines subdirectories for components, hooks, styles, configuration, and testing within the library.

```bash
packages/
├── lib/                    # Main component library
│   ├── src/
│   │   ├── components/     # Component implementations
│   │   ├── hooks/          # Reusable React hooks
│   │   ├── lib/            # Utility functions
│   │   ├── styles/         # Theme system and design tokens
│   │   ├── config/         # Configuration and context
│   │   ├── flow/           # Flow diagram components
│   │   └── types.ts        # Global type definitions
│   ├── tests/              # Unit tests
│   └── dist/               # Built output
└── docs/                   # Documentation site
    ├── src/app/docs/       # Documentation pages
    └── src/components/     # Example components
```

--------------------------------

### Tailwind CSS v3 to v4 Migration Example

Source: https://github.com/g4rcez/components/blob/main/docs/TAILWIND_V4_INTEGRATION.md

Provides a code comparison illustrating the migration from Tailwind CSS v3 to v4. It highlights the shift from viewport-based responsive classes (e.g., `md:grid-cols-2`) to container query modifiers (e.g., `@md:grid-cols-2`) and the use of `@container` on parent elements.

```tsx
// Before (Tailwind v3)
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card className="p-4 md:p-6">
    <h3 className="text-lg md:text-xl">Title</h3>
  </Card>
</div>

// After (Tailwind v4)
<div className="@container">
  <div className="grid @sm:grid-cols-1 @md:grid-cols-2 @lg:grid-cols-3 gap-4">
    <Card className="@container @sm:p-4 @md:p-6">
      <h3 className="@sm:text-lg @md:text-xl">Title</h3>
    </Card>
  </div>
</div>

```

--------------------------------

### Core Components - @g4rcez/components

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Foundation components offering basic functionality and polymorphic rendering capabilities. Includes Button, Polymorph, RenderOnView, and Tag.

```markdown
## 🔧 Core Components

Foundation components that provide basic functionality and polymorphic capabilities.

| Component        | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| **Button**       | Versatile button with multiple variants and polymorphic rendering   |
| **Polymorph**    | Base polymorphic component for rendering as different HTML elements |
| **RenderOnView** | Performance optimization component with intersection observer       |
| **Tag**          | Label/badge component for metadata and status display               |
```

--------------------------------

### Example: Interactive Cards with State

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Provides an example of an interactive Card component that uses React state to manage expandable content.

```javascript
import React, { useState } from 'react';
import { Card } from "@g4rcez/components/card";

const InteractiveCard = () => {
  const [expanded, setExpanded] = useState(false);

  return (
    <Card>
      <Card.Title title="Expandable Content">
        <button
          onClick={() => setExpanded(!expanded)}
          className="text-blue-500 hover:text-blue-700"
        >
          {expanded ? "Collapse" : "Expand"}
        </button>
      </Card.Title>

      <div>
        <p>Always visible content.</p>
        {expanded && (
          <div className="mt-4 p-4 bg-gray-50 rounded">
            <p>Additional content that can be toggled.</p>
          </div>
        )}
      </div>
    </Card>
  );
};

export default InteractiveCard;
```

--------------------------------

### Component File Structure and Naming

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

Guidelines for structuring and naming component files within the project, emphasizing consistency and readability. Includes naming conventions for components, hooks, utilities, and CSS classes.

```tsx
// 1. Imports
import React from "react";

// 2. Types and interfaces
interface Props {}

// 3. Component implementation
export const Component = () => {};

// 4. Display name
Component.displayName = "Component";
```

--------------------------------

### Custom String Mask Examples

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Provides examples of using custom string masks for phone numbers, CPF, dates, and credit card numbers.

```tsx
// Phone number
<Input mask="(99) 99999-9999" placeholder="Phone" />

// CPF (Brazilian tax ID)
<Input mask="999.999.999-99" placeholder="CPF" />

// Date
<Input mask="99/99/9999" placeholder="DD/MM/YYYY" />

// Credit card
<Input mask="9999 9999 9999 9999" placeholder="Card number" />
```

--------------------------------

### Polymorph Component Best Practices

Source: https://github.com/g4rcez/components/blob/main/docs/components/Polymorph.md

Outlines best practices for using the Polymorph component, including default element provision, type safety, ref forwarding, prop spreading, and documentation.

```markdown
1. **Default Element**: Always provide a sensible default for the `as` prop
2. **Type Safety**: Leverage TypeScript's type checking for prop validation
3. **Ref Forwarding**: Always forward refs when creating polymorphic components
4. **Prop Spreading**: Use proper prop spreading to maintain element-specific props
5. **Documentation**: Document which elements are supported and recommended
```

--------------------------------

### Pull Request Template

Source: https://github.com/g4rcez/components/blob/main/CONTRIBUTING.md

A standard template for pull requests, ensuring all necessary information is provided for review. Includes sections for description, type of change, testing, screenshots, and a checklist.

```markdown
## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] Unit tests added/updated
- [ ] Manual testing completed
- [ ] Accessibility tested

## Screenshots

(If applicable)

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
```

--------------------------------

### Dismissible Alert Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Alert.md

Provides an example of a dismissible alert using the 'open' and 'onClose' props to manage its visibility state with React's useState hook.

```tsx
const [showAlert, setShowAlert] = useState(true);

<Alert
  theme="success"
  title="Welcome!"
  open={showAlert}
  onClose={() => setShowAlert(false)}
>
  Thanks for joining our platform.
</Alert>;
```

--------------------------------

### Polymorph Component Examples: Basic Elements

Source: https://github.com/g4rcez/components/blob/main/docs/components/Polymorph.md

Provides examples of using Polymorph for default span rendering, as a button with an onClick handler, and as a link with href and target attributes.

```tsx
// Renders as span (default)
<Polymorph>Default span</Polymorph>

// Renders as button
<Polymorph as="button" onClick={() => console.log('clicked')}>Button</Polymorph>

// Renders as link
<Polymorph as="a" href="https://example.com" target="_blank">External Link</Polymorph>
```

--------------------------------

### Example: Checkbox Sizes

Source: https://github.com/g4rcez/components/blob/main/docs/components/Checkbox.md

Demonstrates how to change the visual size of the checkbox component using the `size` prop.

```tsx
<div className="space-y-4">
  <Checkbox size="medium">Medium checkbox (default)</Checkbox>

  <Checkbox size="large">Large checkbox</Checkbox>
</div>
```

--------------------------------

### Floating Components - @g4rcez/components

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Overlay components utilizing Floating UI for advanced positioning. Includes Modal, Dropdown, Tooltip, and Command Palette for interactive elements.

```markdown
## 🎈 Floating Components

Overlay components using Floating UI for positioning.

| Component          | Description                              |
| ------------------ | ---------------------------------------- |
| **CommandPalette** | Command palette with search and actions  |
| **Dropdown**       | Dropdown menu component                  |
| **Expand**         | Expandable content container             |
| **Menu**           | Context menu component                   |
| **Modal**          | Modal dialog with multiple display types |
| **Toolbar**        | Floating toolbar component               |
| **Tooltip**        | Hover tooltip component                  |
```

--------------------------------

### Example: Disabled Checkboxes

Source: https://github.com/g4rcez/components/blob/main/docs/components/Checkbox.md

Shows how to use the `disabled` prop to make checkboxes non-interactive, both when checked and unchecked.

```tsx
<div className="space-y-2">
  <Checkbox disabled checked>
    This option is disabled and checked
  </Checkbox>

  <Checkbox disabled>This option is disabled and unchecked</Checkbox>
</div>
```

--------------------------------

### Basic Input Usage

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Shows the fundamental way to render the Input component with a placeholder.

```tsx
<Input placeholder="Enter text..." />
```

--------------------------------

### Input with Validation Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Demonstrates how to implement input validation for the Input component, specifically for email format.

```tsx
const [email, setEmail] = useState("");
const [error, setError] = useState("");

const validateEmail = (value: string) => {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(value)) {
    setError("Please enter a valid email address");
  } else {
    setError("");
  }
};

<Input
  type="email"
  placeholder="Email address"
  value={email}
  onChange={(e) => {
    setEmail(e.target.value);
    validateEmail(e.target.value);
  }}
  error={error}
/>;
```

--------------------------------

### Example: Nested Cards

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Shows how to nest Card components within each other to create complex, multi-level layouts.

```tsx
<Card title="Main Dashboard">
  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
    <Card title="Statistics">
      <div>Chart content here</div>
    </Card>

    <Card title="Recent Activity">
      <ul>
        <li>User logged in</li>
        <li>New order received</li>
        <li>Payment processed</li>
      </ul>
    </Card>
  </div>
</Card>
```

--------------------------------

### Individual Component Imports

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Shows how to import specific components either individually from their respective paths or from the main package.

```tsx
// Import specific components
import { Button } from "@g4rcez/components/button";
import { Input } from "@g4rcez/components/input";
import { Modal } from "@g4rcez/components/modal";

// Or import from main package
import { Button, Input, Modal } from "@g4rcez/components";
```

--------------------------------

### Example: Loading Checkbox State

Source: https://github.com/g4rcez/components/blob/main/docs/components/Checkbox.md

Illustrates the `loading` prop, which visually indicates an ongoing operation and disables the checkbox.

```tsx
const [loading, setLoading] = useState(false);
const [subscribed, setSubscribed] = useState(false);

const handleSubscribe = async (checked: boolean) => {
  setLoading(true);
  try {
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1000));
    setSubscribed(checked);
  } finally {
    setLoading(false);
  }
};

<Checkbox
  checked={subscribed}
  onChange={(e) => handleSubscribe(e.target.checked)}
  loading={loading}
>
  Subscribe to newsletter
</Checkbox>;
```

--------------------------------

### Theme System

Source: https://github.com/g4rcez/components/blob/main/COMPONENTS.md

Allows customization of the component library's theme by providing a `ComponentsProvider` with a custom theme object.

```javascript
import { ComponentsProvider } from "@g4rcez/components";

const customTheme = {
  colors: {
    primary: "#your-color",
  },
};

<ComponentsProvider theme={customTheme}>
  <App />
</ComponentsProvider>;
```

--------------------------------

### Product Cards Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Shows a Card component used for displaying product information, specifically a pricing plan. It includes a title with a price, a list of features, and a call-to-action button.

```tsx
<Card>
  <Card.Title title="Premium Plan">
    <span className="text-2xl font-bold text-green-600">$29/mo</span>
  </Card.Title>

  <ul className="space-y-2">
    <li>✓ Unlimited projects</li>
    <li>✓ Priority support</li>
    <li>✓ Advanced analytics</li>
  </ul>

  <button className="w-full mt-4 py-2 bg-blue-500 text-white rounded">
    Choose Plan
  </button>
</Card>
```

--------------------------------

### Display Components - @g4rcez/components

Source: https://github.com/g4rcez/components/blob/main/docs/COMPONENT_INDEX.md

Components designed for presenting information and organizing content effectively. Includes Alert, Card, Tabs, and others for various display needs.

```markdown
## 🎨 Display Components

Components for presenting information and organizing content.

| Component         | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| **Alert**         | Notification and message display with animations           |
| **Calendar**      | Calendar display and date selection                        |
| **Card**          | Container component with header, body, and footer sections |
| **Empty**         | Empty state placeholder component                          |
| **List**          | List display component with virtualization support         |
| **Notifications** | Toast notification system                                  |
| **Progress**      | Progress indicators and loading states                     |
| **Shortcut**      | Keyboard shortcut display component                        |
| **Skeleton**      | Loading skeleton placeholders                              |
| **Stats**         | Statistics and metrics display                             |
| **Step**          | Step indicator for multi-step processes                    |
| **Tabs**          | Tab navigation with keyboard support                       |
| **Timeline**      | Timeline and stepper component                             |
```

--------------------------------

### Example: Card.Title with Navigation

Source: https://github.com/g4rcez/components/blob/main/docs/components/Card.md

Utilizes the Card.Title subcomponent to include navigation buttons alongside the card's title.

```tsx
<Card>
  <Card.Title title="Project Overview">
    <button className="px-3 py-1 bg-blue-500 text-white rounded">Edit</button>
    <button className="px-3 py-1 border border-gray-300 rounded">Share</button>
  </Card.Title>

  <div className="space-y-4">
    <p>Project description and details...</p>
    <div>Status: Active</div>
  </div>
</Card>
```

--------------------------------

### Select with Validation Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Select.md

Illustrates how to implement validation for the Select component, displaying an error message when a required option is not selected.

```tsx
const [country, setCountry] = useState("");
const [error, setError] = useState("");

const validateCountry = (value: string) => {
  if (!value) {
    setError("Please select a country");
  } else {
    setError("");
  }
};

<Select
  options={[
    { value: "us", label: "United States" },
    { value: "ca", label: "Canada" },
    { value: "uk", label: "United Kingdom" },
    { value: "de", label: "Germany" },
  ]}
  placeholder="Select country"
  value={country}
  onChange={(e) => {
    setCountry(e.target.value);
    validateCountry(e.target.value);
  }}
  error={error}
  required
/>;
```

--------------------------------

### Example: Checkbox with Error Handling

Source: https://github.com/g4rcez/components/blob/main/docs/components/Checkbox.md

Shows how to display an error message associated with a checkbox, typically used for form validation.

```tsx
const [agreed, setAgreed] = useState(false);
const [error, setError] = useState("");

const handleSubmit = () => {
  if (!agreed) {
    setError("You must accept the terms to continue");
  } else {
    setError("");
    // Proceed with submission
  }
};

<Checkbox
  checked={agreed}
  onChange={(e) => {
    setAgreed(e.target.checked);
    if (e.target.checked) setError("");
  }}
  error={error}
>
  I agree to the privacy policy
</Checkbox>;
```

--------------------------------

### Dynamic Mask Example

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Illustrates creating a dynamic mask for the Input component where the mask changes based on the input value.

```tsx
const dynamicMask = (value: string) => {
  // Different mask based on input length
  if (value.length <= 11) {
    return "999.999.999-99"; // CPF
  }
  return "99.999.999/9999-99"; // CNPJ
};

<Input mask={dynamicMask} placeholder="CPF or CNPJ" />;
```

--------------------------------

### Button Component Unit Test

Source: https://github.com/g4rcez/components/blob/main/ARCHITECTURE.md

Provides an example of a unit test for the Button component using Vitest and React Testing Library. It verifies that the button renders with the correct CSS classes based on its variant prop.

```tsx
// Component test example
describe("Button", () => {
  it("renders with correct variant", () => {
    render(<Button variant="primary">Test</Button>);
    expect(screen.getByRole("button")).toHaveClass("primary-classes");
  });
});
```

--------------------------------

### Import Input Component

Source: https://github.com/g4rcez/components/blob/main/docs/components/Input.md

Demonstrates how to import the Input component from the @g4rcez/components library.

```tsx
import { Input } from "@g4rcez/components/input";
```

--------------------------------

### Component Exports

Source: https://github.com/g4rcez/components/blob/main/ARCHITECTURE.md

Demonstrates the export strategy for components, including a main export for all components and individual exports for better tree-shaking support. This optimizes bundle size by allowing users to import only the components they need.

```typescript
// Main export (all components)
export * from "./components";

// Individual exports (tree-shaking friendly)
export { Button } from "./components/core/button";
export { Input } from "./components/form/input";
```