npm package: @simpledotstudio/simple-text
Description: SimpleText - A reusable React component
Author: SimpleStudio
Latest version: 2.0.0

# SimpleText

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

## Installation

```bash
npm install @simpledotstudio/simple-text
```

## Usage

```tsx
import { SimpleText } from '@simpledotstudio/simple-text';

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

## 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
<SimpleText as="h1">Page Title</SimpleText>
<SimpleText as="h2" variant="primary">Section Heading</SimpleText>
<SimpleText as="h3" weight="medium">Subsection</SimpleText>
```

### Text Variants

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

### Text Sizes

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

### Text Utilities

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

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

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

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

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

### Semantic HTML

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

### Custom Styling

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

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

## 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 {
  SimpleTextProps,
  TextElement,
  TextVariant,
  TextSize,
  TextWeight,
  TextAlign,
  TextTransform
} from '@simpledotstudio/simple-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
```