npm package: @pagedotapp/page-text
Description: PageText - A reusable React component
Author: PageStudio
Latest version: 0.0.0-alpha.14

# PageText

A flexible text component that can render various HTML text elements with consistent styling and typography options.

## Installation

```bash
npm install @pagedotapp/page-text
```

## Usage

```tsx
import { PageText } from "@pagedotapp/page-text"

function App() {
	return (
		<>
			<PageText as="h1">Main Heading</PageText>
			<PageText as="p" variant="muted">
				This is a paragraph with muted text color.
			</PageText>
			<PageText as="strong" variant="primary">
				Important text
			</PageText>
		</>
	)
}
```

## Props

| Prop                 | Type              | Default          | Description                                                                         |
| -------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `children`           | `React.ReactNode` | -                | Text content                                                                        |
| `as`                 | `TextElement`     | `'p'`            | HTML element to render (h1-h6, p, span, strong, em, etc.)                           |
| `variant`            | `TextVariant`     | `'default'`      | Visual variant (default, primary, secondary, muted, success, warning, danger, info) |
| `size`               | `TextSize`        | Based on element | Text size (xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl)                                  |
| `weight`             | `TextWeight`      | Based on element | Font weight (thin, light, normal, medium, semibold, bold, extrabold, black)         |
| `align`              | `TextAlign`       | -                | Text alignment (left, center, right, justify)                                       |
| `transform`          | `TextTransform`   | -                | Text transformation (uppercase, lowercase, capitalize)                              |
| `truncate`           | `boolean`         | `false`          | Whether text should be truncated with ellipsis                                      |
| `maxLines`           | `number`          | -                | Maximum number of lines before truncating (requires truncate)                       |
| `preserveWhitespace` | `boolean`         | `false`          | Whether to preserve whitespace                                                      |
| `className`          | `string`          | `''`             | Additional CSS class name                                                           |
| `onClick`            | `function`        | -                | Click handler                                                                       |

## Examples

### Headings

```tsx
<PageText as="h1">Page Title</PageText>
<PageText as="h2" variant="primary">Section Heading</PageText>
<PageText as="h3" weight="medium">Subsection</PageText>
```

### Text Variants

```tsx
<PageText variant="default">Default text</PageText>
<PageText variant="primary">Primary text</PageText>
<PageText variant="secondary">Secondary text</PageText>
<PageText variant="muted">Muted text</PageText>
<PageText variant="success">Success text</PageText>
<PageText variant="warning">Warning text</PageText>
<PageText variant="danger">Error text</PageText>
<PageText variant="info">Info text</PageText>
```

### Text Sizes

```tsx
<PageText size="xs">Extra small text</PageText>
<PageText size="sm">Small text</PageText>
<PageText size="md">Medium text</PageText>
<PageText size="lg">Large text</PageText>
<PageText size="xl">Extra large text</PageText>
<PageText size="2xl">2X large text</PageText>
```

### Text Utilities

```tsx
// Truncation
<PageText truncate>
  This is a very long text that will be truncated with ellipsis
</PageText>

// Multi-line truncation
<PageText truncate maxLines={3}>
  This is a very long text that spans multiple lines
  and will be truncated after 3 lines with ellipsis...
</PageText>

// Text alignment
<PageText align="center">Centered text</PageText>
<PageText align="right">Right-aligned text</PageText>

// Text transformation
<PageText transform="uppercase">uppercase text</PageText>
<PageText transform="capitalize">capitalized text</PageText>

// Preserve whitespace
<PageText preserveWhitespace>
  Text   with   multiple   spaces
  and line breaks preserved
</PageText>
```

### Semantic HTML

```tsx
<PageText as="strong">Bold/important text</PageText>
<PageText as="em">Emphasized text</PageText>
<PageText as="small">Small print</PageText>
<PageText as="mark">Highlighted text</PageText>
<PageText as="del">Deleted text</PageText>
<PageText as="ins">Inserted text</PageText>
<PageText as="code">console.log('Code text')</PageText>
<PageText as="blockquote">
  "This is a blockquote"
</PageText>
```

### Custom Styling

```tsx
// Override default size/weight
<PageText as="h1" size="md" weight="normal">
  Small, normal weight heading
</PageText>

// Add custom className
<PageText className="custom-text-class">
  Text with custom styling
</PageText>
```

## Smart Defaults

The component automatically applies appropriate default sizes and weights based on the element type:

- **Headings (h1-h6)**: Bold weight with progressively smaller sizes
- **Strong**: Bold weight
- **Label/Legend**: Medium weight
- **Small/Code**: Small size

These defaults can be overridden using the `size` and `weight` props.

## TypeScript

The component exports the following types:

```typescript
import type {
	PageTextProps,
	TextElement,
	TextVariant,
	TextSize,
	TextWeight,
	TextAlign,
	TextTransform,
} from "@pagedotapp/page-text"
```

## Styling

The component uses CSS modules for styling. You can override styles by passing a custom `className` or by targeting the component's CSS classes in your global styles.

## Development

To run the component in development mode:

```bash
npm run storybook
```

To run tests:

```bash
npm run test
```

To lint the component:

```bash
npm run lint
```