@restnfeel/agentc-starter-kit/docs/components.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# Component Documentation

## Table of Contents

- [UI Components](#ui-components)
- [Section Components](#section-components)
- [Auth Components](#auth-components)
- [Dashboard Components](#dashboard-components)
- [Layout Components](#layout-components)
- [Legal Components](#legal-components)

## UI Components

### Button

A versatile button component with multiple variants and states.

```tsx
import { Button } from "agentc-starter-kit";

// Basic usage
<Button>Click me</Button>

// With variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

// With sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// States
<Button loading>Loading...</Button>
<Button disabled>Disabled</Button>

// With icon
<Button leftIcon={<YourIcon />}>With Icon</Button>
```

**Props:**

- `variant`: "primary" | "secondary" | "outline" | "ghost"
- `size`: "sm" | "md" | "lg"
- `loading`: boolean
- `disabled`: boolean
- `leftIcon`: React.ReactNode
- `rightIcon`: React.ReactNode
- `fullWidth`: boolean

### Input

Form input component with label, error states, and validation.

```tsx
import { Input } from "agentc-starter-kit";

// Basic usage
<Input placeholder="Enter text" />

// With label
<Input label="Email" type="email" />

// With error state
<Input
  label="Password"
  type="password"
  error="Password is required"
/>

// Disabled state
<Input disabled placeholder="Disabled input" />
```

**Props:**

- `label`: string
- `type`: "text" | "email" | "password" | "tel" | "url"
- `placeholder`: string
- `error`: string
- `disabled`: boolean
- `required`: boolean

### Card

Container component for grouping related content.

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardContent,
  CardFooter,
} from "agentc-starter-kit";

<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>Card content goes here</CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>;
```

### Modal

Overlay component for dialogs and modals.

```tsx
import {
  Modal,
  ModalHeader,
  ModalTitle,
  ModalContent,
} from "agentc-starter-kit";

<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
  <ModalHeader>
    <ModalTitle>Modal Title</ModalTitle>
  </ModalHeader>
  <ModalContent>Modal content</ModalContent>
</Modal>;
```

### Loading

Loading spinner component with multiple variants.

```tsx
import { Loading } from "agentc-starter-kit";

// Basic usage
<Loading />

// With text
<Loading text="Loading..." />

// Different sizes
<Loading size="sm" />
<Loading size="lg" />
```

## Section Components

### HeroSection

Primary landing page hero section with call-to-action.

```tsx
import { HeroSection } from "agentc-starter-kit";

<HeroSection
  title="Welcome to Our Platform"
  subtitle="The best solution for your business needs"
  ctaText="Get Started"
  onCtaClick={() => handleGetStarted()}
  backgroundImage="/hero-bg.jpg"
/>;
```

**Props:**

- `title`: string (required)
- `subtitle`: string
- `ctaText`: string
- `onCtaClick`: () => void
- `backgroundImage`: string
- `variant`: "default" | "centered" | "split"

### FeaturesSection

Showcase key features with icons and descriptions.

```tsx
import { FeaturesSection } from "agentc-starter-kit";

const features = [
  {
    title: "Fast Performance",
    description: "Lightning fast loading times",
    icon: <SpeedIcon />,
  },
  {
    title: "Secure",
    description: "Enterprise-grade security",
    icon: <SecurityIcon />,
  },
];

<FeaturesSection title="Why Choose Us" features={features} variant="grid" />;
```

### PricingSection

Display pricing plans with feature comparisons.

```tsx
import { PricingSection } from "agentc-starter-kit";

const plans = [
  {
    name: "Basic",
    price: "$9",
    period: "month",
    features: ["Feature 1", "Feature 2"],
    highlighted: false,
  },
  {
    name: "Pro",
    price: "$29",
    period: "month",
    features: ["All Basic features", "Feature 3", "Feature 4"],
    highlighted: true,
  },
];

<PricingSection
  title="Choose Your Plan"
  plans={plans}
  onSelectPlan={(planId) => handlePlanSelect(planId)}
/>;
```

### TestimonialSection

Customer testimonials and reviews.

```tsx
import { TestimonialSection } from "agentc-starter-kit";

const testimonials = [
  {
    name: "John Doe",
    role: "CEO, Company",
    content: "This product changed our business...",
    avatar: "/avatar1.jpg",
  },
];

<TestimonialSection
  title="What Our Customers Say"
  testimonials={testimonials}
/>;
```

## Dashboard Components

### StatsCard

Display key metrics and statistics.

```tsx
import { StatsCard } from "agentc-starter-kit";

<StatsCard
  title="Total Users"
  value="1,234"
  subtitle="Active users"
  trend={{ value: 12, isPositive: true, label: "vs last month" }}
  icon={<UsersIcon />}
  variant="success"
/>;
```

**Props:**

- `title`: string
- `value`: string | number
- `subtitle`: string
- `trend`: { value: number, isPositive: boolean, label?: string }
- `icon`: React.ReactNode
- `variant`: "default" | "success" | "warning" | "danger"

### DataTable

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

```tsx
import { DataTable } from "agentc-starter-kit";

const columns = [
  { key: "name", label: "Name", sortable: true },
  { key: "email", label: "Email", sortable: true },
  {
    key: "actions",
    label: "Actions",
    render: (value, row) => (
      <Button size="sm" onClick={() => editUser(row.id)}>
        Edit
      </Button>
    ),
  },
];

<DataTable
  data={users}
  columns={columns}
  searchable
  pagination={{
    page: 1,
    pageSize: 10,
    total: 100,
    onPageChange: setPage,
    onPageSizeChange: setPageSize,
  }}
/>;
```

### UserProfile

User profile management component.

```tsx
import { UserProfile } from "agentc-starter-kit";

<UserProfile
  user={currentUser}
  editable
  onSave={(updatedUser) => saveUser(updatedUser)}
  fields={[
    { key: "name", label: "Full Name", editable: true },
    { key: "email", label: "Email", editable: true },
    { key: "role", label: "Role", editable: false },
  ]}
/>;
```

### NotificationSettings

Manage notification preferences.

```tsx
import { NotificationSettings } from "agentc-starter-kit";

const categories = [
  {
    id: "security",
    title: "Security Notifications",
    settings: [
      {
        id: "login_alerts",
        label: "Login Alerts",
        type: "email",
        enabled: true,
      },
    ],
  },
];

<NotificationSettings
  categories={categories}
  onSave={(settings) => saveNotificationSettings(settings)}
/>;
```

## Auth Components

### AuthProvider

Authentication context provider using NextAuth.

```tsx
import { AuthProvider } from "agentc-starter-kit";

function App({ children }) {
  return <AuthProvider>{children}</AuthProvider>;
}
```

## Legal Components

### PrivacyPolicy

Customizable privacy policy component.

```tsx
import { PrivacyPolicy } from "agentc-starter-kit";

<PrivacyPolicy
  companyName="Your Company"
  contactEmail="privacy@company.com"
  showTableOfContents
  enablePrint
/>;
```

### TermsOfService

Terms of service component.

```tsx
import { TermsOfService } from "agentc-starter-kit";

<TermsOfService companyName="Your Company" contactEmail="legal@company.com" />;
```

### ConsentManager

GDPR-compliant cookie consent management.

```tsx
import { ConsentManager } from "agentc-starter-kit";

<ConsentManager
  showBanner={!hasConsented}
  onConsentUpdate={(consents) => handleConsents(consents)}
  privacyPolicyUrl="/privacy"
  termsUrl="/terms"
/>;
```

## Best Practices

### Styling

All components use Tailwind CSS classes and support dark mode out of the box. You can customize the theme by modifying your Tailwind configuration:

```js
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#eff6ff",
          500: "#3b82f6",
          600: "#2563eb",
          // ... more shades
        },
      },
    },
  },
};
```

### TypeScript

All components are fully typed. Import types alongside components:

```tsx
import { Button, type ButtonProps } from "agentc-starter-kit";

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};
```

### Tree Shaking

Import only the components you need to keep bundle size minimal:

```tsx
// ✅ Good - imports only what's needed
import { Button, Card } from "agentc-starter-kit";

// ❌ Avoid - imports entire library
import * as Components from "agentc-starter-kit";
```

### Accessibility

All components follow WCAG guidelines and include:

- Proper ARIA attributes
- Keyboard navigation
- Screen reader support
- Focus management

### Error Handling

Components include built-in error boundaries and graceful degradation:

```tsx
import { ErrorBoundary } from "agentc-starter-kit";

<ErrorBoundary fallback={<div>Something went wrong</div>}>
  <YourComponent />
</ErrorBoundary>;
```