# Typography

## Introduction

The Typography component is a core component for displaying text. It is based on Joy UI Typography and provides a variety of text levels and styles. You can apply consistent typography across all text elements such as headings, body text, and labels.

```tsx
<Typography children="Typography" />
```

| Field | Description | Default |
| ----- | ----------- | ------- |
| level | —           | —       |
| color | —           | —       |

## Usage

```tsx
import { Typography } from '@ceed/ads';

function MyComponent() {
  return (
    <div>
      <Typography level="h1">Main Heading</Typography>
      <Typography level="body-md">This is body text.</Typography>
      <Typography level="body-sm" color="neutral">
        This is supporting description text.
      </Typography>
    </div>
  );
}
```

## Typography Levels

### Headings

Levels for headings. Use them to clearly define page structure.

```tsx
<Typography level="h1">H1 - Main page heading</Typography>
<Typography level="h2">H2 - Section heading</Typography>
<Typography level="h3">H3 - Subsection heading</Typography>
<Typography level="h4">H4 - Detailed heading</Typography>
```

### Titles

Used for important titles or emphasized text.

```tsx
<Typography level="title-lg">Large Title</Typography>
<Typography level="title-md">Medium Title</Typography>
<Typography level="title-sm">Small Title</Typography>
```

### Body Text

Levels for body text. Use these for most readable content.

```tsx
<Typography level="body-lg">Large body text</Typography>
<Typography level="body-md">Regular body text</Typography>
<Typography level="body-sm">Small body text</Typography>
<Typography level="body-xs">Extra small text</Typography>
```

## Common Use Cases

### Page Structure

```tsx
function ArticlePage() {
  return (
    <article>
      <Typography level="h1" sx={{ mb: 2 }}>
        Article Title
      </Typography>

      <Typography level="body-sm" color="neutral" sx={{ mb: 3 }}>
        January 15, 2024 · Written by John Doe
      </Typography>

      <Typography level="body-md" sx={{ mb: 2 }}>
        The main content of the article goes here. This text uses a readable size and line spacing.
      </Typography>

      <Typography level="h2" sx={{ mt: 4, mb: 2 }}>
        Section Title
      </Typography>

      <Typography level="body-md">The section content continues here.</Typography>
    </article>
  );
}
```

### Card Content

```tsx
<Card>
  <CardContent>
    <Typography level="title-md" sx={{ mb: 1 }}>
      Product Name
    </Typography>

    <Typography level="body-sm" color="neutral" sx={{ mb: 2 }}>
      Category: Electronics
    </Typography>

    <Typography level="body-md" sx={{ mb: 2 }}>
      A detailed description of the product goes here.
    </Typography>

    <Typography level="title-lg" color="primary">
      ₩199,000
    </Typography>
  </CardContent>
</Card>
```

### Form Labels and Help Text

```tsx
<Stack spacing={2}>
  <FormControl>
    <Typography level="title-sm" component="label">
      Username
    </Typography>
    <Input placeholder="Enter your name" />
    <Typography level="body-xs" color="neutral">
      Please enter your real name.
    </Typography>
  </FormControl>

  <FormControl error>
    <Typography level="title-sm" component="label">
      Email Address
    </Typography>
    <Input placeholder="email@example.com" />
    <Typography level="body-xs" color="danger">
      The email format is invalid.
    </Typography>
  </FormControl>
</Stack>
```

> 💡 **Tip: Use built-in form props instead**
>
> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
> Form을 구성할 때는 Typography로 직접 label/helperText를 만드는 것보다 각 컴포넌트의 내장 prop을 사용하는 것이 권장됩니다.
>
> ```tsx
> // ✅ Recommended: 컴포넌트 내장 prop 사용
> <Input label="Username" helperText="Please enter your real name." />
>
> // ❌ Not recommended: Typography로 직접 구성
> <FormControl>
>   <Typography level="title-sm" component="label">Username</Typography>
>   <Input placeholder="Enter your name" />
>   <Typography level="body-xs" color="neutral">Please enter your real name.</Typography>
> </FormControl>
> ```

### Status and Indicators

```tsx
<Stack spacing={2}>
  <Box>
    <Typography level="body-md">Server Status:</Typography>
    <Typography level="body-md" color="success">
      Operating Normally
    </Typography>
  </Box>

  <Box>
    <Typography level="body-md">Last Updated:</Typography>
    <Typography level="body-sm" color="neutral">
      2 minutes ago
    </Typography>
  </Box>
</Stack>
```

### List Content

```tsx
<Stack spacing={1}>
  <Typography level="title-md">Todo List</Typography>

  {todoItems.map((item) => (
    <Box key={item.id} sx={{ pl: 2 }}>
      <Typography
        level="body-md"
        sx={{
          textDecoration: item.completed ? 'line-through' : 'none',
          color: item.completed ? 'neutral.500' : 'text.primary',
        }}
      >
        {item.text}
      </Typography>
      <Typography level="body-xs" color="neutral">
        {item.dueDate}
      </Typography>
    </Box>
  ))}
</Stack>
```

## Colors

Typography supports various colors:

```tsx
<Stack spacing={1}>
  <Typography color="primary">Primary color</Typography>
  <Typography color="neutral">Neutral color</Typography>
  <Typography color="danger">Danger color</Typography>
  <Typography color="success">Success color</Typography>
  <Typography color="warning">Warning color</Typography>
</Stack>
```

## Component Prop

You can render it as a different HTML element or React component:

```tsx
<Typography level="h1" component="h2">
  h1 style rendered as an h2 tag
</Typography>

<Typography level="body-md" component="span">
  Inline text
</Typography>

<Typography level="title-md" component={Link} href="/page">
  Rendered as a Link component
</Typography>
```

## Responsive Typography

You can use responsive levels:

```tsx
<Typography
  level={{ xs: 'h3', sm: 'h2', md: 'h1' }}
  sx={{
    fontSize: { xs: '1.5rem', sm: '2rem', md: '2.5rem' },
  }}
>
  Responsive Heading
</Typography>
```

## Best Practices

1. **Semantic Structure**: Use heading levels in order to create a clear document structure.

```tsx
// ✅ Correct order
<Typography level="h1">Main heading</Typography>
<Typography level="h2">Section heading</Typography>
<Typography level="h3">Subsection</Typography>

// ❌ Incorrect order
<Typography level="h1">Main heading</Typography>
<Typography level="h3">Section heading</Typography>
```

2. **Consistency**: Use the same level for text serving the same purpose.

3. **Readability**: Provide proper line spacing and paragraph separation for body text.

4. **Color Contrast**: Maintain sufficient color contrast to ensure accessibility.

## Accessibility

- Use appropriate semantic HTML tags
- Support screen readers
- Ensure keyboard navigation (when used as a link or button)
- Maintain sufficient color contrast

Typography plays a key role in effectively conveying information and creating visual hierarchy in user interfaces. By choosing appropriate levels and styles, you can create content that is easy to read and accessible.
