# API Reference

Complete API documentation for all AgentC Starter Kit components.

## UI Components

### Button

A versatile button component with multiple variants and states.

#### Props

| Prop        | Type                                               | Default     | Description            |
| ----------- | -------------------------------------------------- | ----------- | ---------------------- |
| `variant`   | `'primary' \| 'secondary' \| 'outline' \| 'ghost'` | `'primary'` | Button style variant   |
| `size`      | `'sm' \| 'md' \| 'lg'`                             | `'md'`      | Button size            |
| `loading`   | `boolean`                                          | `false`     | Show loading spinner   |
| `disabled`  | `boolean`                                          | `false`     | Disable button         |
| `fullWidth` | `boolean`                                          | `false`     | Make button full width |
| `children`  | `ReactNode`                                        | -           | Button content         |
| `onClick`   | `() => void`                                       | -           | Click handler          |
| `className` | `string`                                           | -           | Additional CSS classes |

#### Example

```tsx
<Button
  variant="primary"
  size="lg"
  loading={isLoading}
  onClick={() => handleClick()}
>
  Submit
</Button>
```

### Input

Form input component with validation support.

#### Props

| Prop          | Type                                          | Default  | Description            |
| ------------- | --------------------------------------------- | -------- | ---------------------- |
| `type`        | `'text' \| 'email' \| 'password' \| 'number'` | `'text'` | Input type             |
| `placeholder` | `string`                                      | -        | Placeholder text       |
| `value`       | `string`                                      | -        | Input value            |
| `onChange`    | `(value: string) => void`                     | -        | Change handler         |
| `onBlur`      | `() => void`                                  | -        | Blur handler           |
| `error`       | `string`                                      | -        | Error message          |
| `disabled`    | `boolean`                                     | `false`  | Disable input          |
| `required`    | `boolean`                                     | `false`  | Mark as required       |
| `label`       | `string`                                      | -        | Input label            |
| `className`   | `string`                                      | -        | Additional CSS classes |

#### Example

```tsx
<Input
  type="email"
  label="Email Address"
  placeholder="Enter your email"
  value={email}
  onChange={setEmail}
  error={emailError}
  required
/>
```

### Card

Container component with optional header, content, and footer sections.

#### Props

| Prop        | Type                      | Default     | Description            |
| ----------- | ------------------------- | ----------- | ---------------------- |
| `variant`   | `'default' \| 'elevated'` | `'default'` | Card style variant     |
| `children`  | `ReactNode`               | -           | Card content           |
| `className` | `string`                  | -           | Additional CSS classes |

#### Example

```tsx
<Card variant="elevated">
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Card content goes here</p>
  </CardContent>
</Card>
```

### Modal

Overlay dialog component for displaying content above the page.

#### Props

| Prop       | Type                           | Default | Description             |
| ---------- | ------------------------------ | ------- | ----------------------- |
| `isOpen`   | `boolean`                      | `false` | Modal visibility        |
| `onClose`  | `() => void`                   | -       | Close handler           |
| `title`    | `string`                       | -       | Modal title             |
| `children` | `ReactNode`                    | -       | Modal content           |
| `size`     | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'`  | Modal size              |
| `closable` | `boolean`                      | `true`  | Show close button       |
| `backdrop` | `boolean`                      | `true`  | Click backdrop to close |

#### Example

```tsx
<Modal
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  title="Confirm Action"
  size="md"
>
  <p>Are you sure you want to continue?</p>
  <div className="flex gap-2 mt-4">
    <Button onClick={handleConfirm}>Confirm</Button>
    <Button variant="outline" onClick={() => setIsModalOpen(false)}>
      Cancel
    </Button>
  </div>
</Modal>
```

### Loading

Loading spinner component with customizable size and color.

#### Props

| Prop        | Type                   | Default     | Description            |
| ----------- | ---------------------- | ----------- | ---------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`      | Spinner size           |
| `color`     | `string`               | `'primary'` | Spinner color          |
| `text`      | `string`               | -           | Loading text           |
| `className` | `string`               | -           | Additional CSS classes |

#### Example

```tsx
<Loading size="lg" text="Loading..." />
```

## Section Components

### HeroSection

Hero banner component for landing pages.

#### Props

| Prop                  | Type                                 | Default     | Description               |
| --------------------- | ------------------------------------ | ----------- | ------------------------- |
| `title`               | `string`                             | -           | Main heading              |
| `subtitle`            | `string`                             | -           | Subheading text           |
| `ctaText`             | `string`                             | -           | Primary CTA button text   |
| `secondaryCtaText`    | `string`                             | -           | Secondary CTA button text |
| `onCtaClick`          | `() => void`                         | -           | Primary CTA handler       |
| `onSecondaryCtaClick` | `() => void`                         | -           | Secondary CTA handler     |
| `backgroundImage`     | `string`                             | -           | Background image URL      |
| `variant`             | `'default' \| 'centered' \| 'split'` | `'default'` | Layout variant            |
| `className`           | `string`                             | -           | Additional CSS classes    |

#### Example

```tsx
<HeroSection
  title="Build Amazing Apps Fast"
  subtitle="The complete starter kit for your Next.js applications"
  ctaText="Get Started"
  secondaryCtaText="Learn More"
  onCtaClick={() => navigate("/signup")}
  onSecondaryCtaClick={() => navigate("/docs")}
  variant="centered"
/>
```

### FeaturesSection

Feature showcase component with grid or list layout.

#### Props

| Prop        | Type               | Default  | Description              |
| ----------- | ------------------ | -------- | ------------------------ |
| `title`     | `string`           | -        | Section title            |
| `subtitle`  | `string`           | -        | Section subtitle         |
| `features`  | `Feature[]`        | -        | Array of feature objects |
| `variant`   | `'grid' \| 'list'` | `'grid'` | Layout variant           |
| `className` | `string`           | -        | Additional CSS classes   |

#### Feature Object

```typescript
interface Feature {
  title: string;
  description: string;
  icon?: string | ReactNode;
  image?: string;
}
```

#### Example

```tsx
<FeaturesSection
  title="Why Choose Our Platform"
  subtitle="Everything you need to succeed"
  features={[
    {
      title: "Fast Development",
      description: "Build apps in record time",
      icon: "⚡",
    },
    // ... more features
  ]}
  variant="grid"
/>
```

### PricingSection

Pricing table component with plan comparison.

#### Props

| Prop           | Type                       | Default | Description            |
| -------------- | -------------------------- | ------- | ---------------------- |
| `title`        | `string`                   | -       | Section title          |
| `subtitle`     | `string`                   | -       | Section subtitle       |
| `plans`        | `PricingPlan[]`            | -       | Array of pricing plans |
| `onSelectPlan` | `(planId: string) => void` | -       | Plan selection handler |
| `className`    | `string`                   | -       | Additional CSS classes |

#### PricingPlan Object

```typescript
interface PricingPlan {
  id: string;
  name: string;
  price: string;
  period: string;
  description: string;
  features: string[];
  highlighted?: boolean;
  ctaText: string;
}
```

## Dashboard Components

### StatsCard

Statistics display card with trend indicators.

#### Props

| Prop        | Type                                              | Default     | Description            |
| ----------- | ------------------------------------------------- | ----------- | ---------------------- |
| `title`     | `string`                                          | -           | Card title             |
| `value`     | `string \| number`                                | -           | Main value             |
| `subtitle`  | `string`                                          | -           | Additional context     |
| `trend`     | `TrendData`                                       | -           | Trend information      |
| `variant`   | `'default' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant          |
| `loading`   | `boolean`                                         | `false`     | Show loading state     |
| `className` | `string`                                          | -           | Additional CSS classes |

#### TrendData Object

```typescript
interface TrendData {
  value: number;
  isPositive: boolean;
  label: string;
}
```

#### Example

```tsx
<StatsCard
  title="Total Revenue"
  value="$45,678"
  subtitle="This month"
  trend={{
    value: 12,
    isPositive: true,
    label: "vs last month",
  }}
  variant="success"
/>
```

### DataTable

Feature-rich data table with sorting, search, and pagination.

#### Props

| Prop         | Type               | Default     | Description            |
| ------------ | ------------------ | ----------- | ---------------------- |
| `data`       | `T[]`              | -           | Table data array       |
| `columns`    | `Column<T>[]`      | -           | Column definitions     |
| `searchable` | `boolean`          | `false`     | Enable search          |
| `sortable`   | `boolean`          | `true`      | Enable sorting         |
| `pagination` | `PaginationConfig` | -           | Pagination settings    |
| `loading`    | `boolean`          | `false`     | Show loading state     |
| `emptyText`  | `string`           | `'No data'` | Empty state text       |
| `className`  | `string`           | -           | Additional CSS classes |

#### Column Object

```typescript
interface Column<T> {
  key: keyof T;
  label: string;
  sortable?: boolean;
  render?: (value: any, row: T) => ReactNode;
}
```

### UserProfile

User profile management component with editable fields.

#### Props

| Prop        | Type                   | Default | Description            |
| ----------- | ---------------------- | ------- | ---------------------- |
| `user`      | `User`                 | -       | User data object       |
| `editable`  | `boolean`              | `false` | Enable editing         |
| `fields`    | `ProfileField[]`       | -       | Field configuration    |
| `onSave`    | `(user: User) => void` | -       | Save handler           |
| `className` | `string`               | -       | Additional CSS classes |

#### ProfileField Object

```typescript
interface ProfileField {
  key: string;
  label: string;
  editable: boolean;
  type?: "text" | "email" | "date";
}
```

### NotificationSettings

Notification preference management component.

#### Props

| Prop         | Type                                       | Default | Description             |
| ------------ | ------------------------------------------ | ------- | ----------------------- |
| `categories` | `NotificationCategory[]`                   | -       | Notification categories |
| `onSave`     | `(settings: NotificationSettings) => void` | -       | Save handler            |
| `className`  | `string`                                   | -       | Additional CSS classes  |

#### NotificationCategory Object

```typescript
interface NotificationCategory {
  id: string;
  title: string;
  description: string;
  settings: NotificationSetting[];
}

interface NotificationSetting {
  id: string;
  label: string;
  description: string;
  type: "email" | "push" | "sms" | "in-app";
  enabled: boolean;
  required: boolean;
}
```

## Auth Components

### AuthProvider

Authentication context provider using NextAuth.

#### Props

| Prop        | Type          | Default | Description       |
| ----------- | ------------- | ------- | ----------------- |
| `children`  | `ReactNode`   | -       | Child components  |
| `providers` | `Provider[]`  | -       | OAuth providers   |
| `pages`     | `PagesConfig` | -       | Custom auth pages |

#### Example

```tsx
<AuthProvider
  providers={[GoogleProvider, KakaoProvider]}
  pages={{
    signIn: "/auth/signin",
    signUp: "/auth/signup",
  }}
>
  <App />
</AuthProvider>
```

### useAuth Hook

Authentication hook for accessing user state and auth methods.

#### Returns

```typescript
interface AuthState {
  user: User | null;
  isLoading: boolean;
  isAuthenticated: boolean;
  signIn: (provider?: string) => Promise<void>;
  signOut: () => Promise<void>;
  updateUser: (data: Partial<User>) => Promise<void>;
}
```

#### Example

```tsx
function Profile() {
  const { user, isAuthenticated, signOut } = useAuth();

  if (!isAuthenticated) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}
```

## Legal Components

### PrivacyPolicy

Customizable privacy policy component.

#### Props

| Prop                  | Type              | Default | Description           |
| --------------------- | ----------------- | ------- | --------------------- |
| `companyName`         | `string`          | -       | Company name          |
| `contactEmail`        | `string`          | -       | Contact email         |
| `effectiveDate`       | `string`          | -       | Policy effective date |
| `sections`            | `PolicySection[]` | -       | Custom sections       |
| `showTableOfContents` | `boolean`         | `true`  | Show TOC              |
| `printable`           | `boolean`         | `true`  | Enable print function |

### TermsOfService

Terms of service component with similar structure to PrivacyPolicy.

### ConsentManager

GDPR-compliant cookie consent management.

#### Props

| Prop               | Type                              | Default | Description            |
| ------------------ | --------------------------------- | ------- | ---------------------- |
| `privacyPolicyUrl` | `string`                          | -       | Privacy policy URL     |
| `termsUrl`         | `string`                          | -       | Terms of service URL   |
| `onConsentUpdate`  | `(consents: ConsentData) => void` | -       | Consent change handler |
| `defaultConsents`  | `ConsentData`                     | -       | Default consent state  |

#### ConsentData Object

```typescript
interface ConsentData {
  necessary: boolean;
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
}
```

## Layout Components

### Navbar

Navigation component with responsive design.

#### Props

| Prop      | Type        | Default | Description       |
| --------- | ----------- | ------- | ----------------- |
| `logo`    | `ReactNode` | -       | Logo element      |
| `items`   | `NavItem[]` | -       | Navigation items  |
| `actions` | `ReactNode` | -       | Action buttons    |
| `sticky`  | `boolean`   | `false` | Sticky navigation |

### Footer

Footer component with links and social media.

#### Props

| Prop          | Type           | Default | Description        |
| ------------- | -------------- | ------- | ------------------ |
| `companyName` | `string`       | -       | Company name       |
| `links`       | `FooterLink[]` | -       | Footer links       |
| `socialLinks` | `SocialLink[]` | -       | Social media links |
| `copyright`   | `string`       | -       | Copyright text     |

## TypeScript Types

All components are fully typed with TypeScript. Import types for better development experience:

```tsx
import type {
  ButtonProps,
  CardProps,
  HeroSectionProps,
  StatsCardProps,
  User,
  AuthState,
} from "agentc-starter-kit";
```

## Theme Customization

### CSS Custom Properties

Override default theme values:

```css
:root {
  --primary-50: #eff6ff;
  --primary-500: #3b82f6;
  --primary-600: #2563eb;
  /* ... other color variables */
}
```

### Tailwind Configuration

Extend Tailwind theme in your config:

```js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: "var(--primary-50)",
          500: "var(--primary-500)",
          600: "var(--primary-600)",
        },
      },
    },
  },
};
```