npm package: @ro-sch/ui
Description: A UI component library for React.
Latest version: 1.0.0

# Rosch UI

A modern React component library built with TypeScript, styled-components, and atomic design principles.

## 🚀 Features

- **Modern Stack**: React 19, TypeScript 5.8, styled-components 6
- **Design System**: Atomic architecture with comprehensive theme system
- **Type Safety**: Full TypeScript support with detailed interfaces
- **Testing**: Unit tests with Jest and React Testing Library
- **Performance**: Transient props for optimized rendering
- **Documentation**: Auto-generated API documentation with TypeDoc

## 📦 Installation

```bash
# With pnpm (recommended)
pnpm add rosch-ui styled-components

# With npm
npm install rosch-ui styled-components

# With yarn
yarn add rosch-ui styled-components
```

### Peer Dependencies

Make sure you have the following dependencies installed:

```bash
pnpm add react react-dom styled-components
```

## 🎯 Quick Start

### Theme Setup

Wrap your application with the theme provider:

```tsx
import { RoschTheme } from 'rosch-ui';

function App() {
    return (
        <RoschTheme>
            {/* Your application */}
        </RoschTheme>
    );
}
```

### Using Components

```tsx
import { RoschButton, RoschText } from 'rosch-ui';

function Example() {
    return (
        <div>
            <RoschText id="title" fontSize="lg" bold>
                Welcome to Rosch UI
            </RoschText>

            <RoschButton
                id="cta-button"
                label="Get Started"
                onClick={() => console.log('Clicked!')}
                padding="lg"
                bold
            />
        </div>
    );
}
```

## 🧱 Available Components

### RoschButton

Flexible button component with theme support and state management.

```tsx
// Simple button
<RoschButton
    id="simple-btn"
    label="Click me"
    onClick={handleClick}
/>

// Button with custom content
<RoschButton id="custom-btn" onClick={handleClick}>
    <Icon name="download"/>
    <span style={{marginLeft: '8px'}}>Download</span>
</RoschButton>

// Disabled button
<RoschButton
    id="disabled-btn"
    label="Loading..."
    disabled={isLoading}
    onClick={handleSubmit}
/>
```

#### Key Props

- `id` (required): Unique identifier
- `label`: Simple button text
- `children`: Custom React content
- `onClick`: Click event handler
- `disabled`: Disabled state
- `bold`: Bold text styling
- `padding`: Theme-aware spacing
- `radius`: Theme-aware border radius
- `width`, `maxWidth`: Dimensions

### RoschText

Text component with complete typography support.

```tsx
// Simple text
<RoschText id="simple-text">
    This is simple text
</RoschText>

// Styled text
<RoschText
    id="styled-text"
    fontSize="lg"
    bold
    color="primary"
    textDecoration="underline"
>
    Styled text content
</RoschText>
```

#### Key Props

- `id` (required): Unique identifier
- `children`: Text content
- `fontSize`: Font size (theme-aware)
- `bold`: Bold text styling
- `color`: Text color (theme-aware)
- `textDecoration`: Text decoration
- `textAlign`: Text alignment

### RoschTheme

Theme provider for the entire application.

```tsx
import { RoschTheme, defaultTheme } from 'rosch-ui';

// With default theme
<RoschTheme>
    <App/>
</RoschTheme>

// With custom theme
<RoschTheme theme={customTheme}>
    <App/>
</RoschTheme>
```

## 🎨 Theme System

Rosch UI's theme system enables complete customization of colors, spacing, typography, and border radius.

### Default Theme

```tsx
import { defaultTheme } from 'rosch-ui';

// The theme includes:
// - Complete color palette
// - Spacing scale
// - Typography scale  
// - Border radius scale
// - Button and text configurations
```

### Customization

```tsx
import type { Theme } from 'rosch-ui';

const customTheme: Theme = {
    colors: {
        primary: {
            50: '#f0f9ff',
            500: '#3b82f6',
            900: '#1e3a8a'
        },
        // ... other colors
    },
    spacing: {
        sm: '8px',
        md: '16px',
        lg: '24px'
  },
    // ... other properties
};

<RoschTheme theme={customTheme}>
    <App/>
</RoschTheme>
```

## 🛠️ Development

### Prerequisites

- Node.js 18+
- pnpm (recommended)

### Installation

```bash
git clone <repository-url>
cd rosch-ui
pnpm install
```

### Available Scripts

```bash
# Development with hot reload
pnpm dev

# Production build
pnpm build

# Run tests with coverage
pnpm test

# Linting
pnpm lint
pnpm lint:fix

# Documentation
pnpm docs
pnpm docs:preview

# Code formatting
pnpm format
```

### Project Structure

```
src/
├── lib/
│   ├── atoms/              # Atomic components
│   ├── common/             # Common utilities
│   ├── theme/              # Theme system
│   │   ├── theme-components/   # Theme provider
│   │   ├── theme-configs/      # Theme configurations
│   │   ├── theme-interfaces/   # TypeScript types
│   │   └── theme-utils/        # Theme utilities
│   └── index.ts            # Main entry point
└── standalone/             # Development application
```

## 🧪 Testing

The project uses Jest and React Testing Library for testing:

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Generate coverage report
pnpm test --coverage
```

## 📖 Documentation

Complete API documentation is generated with TypeDoc:

```bash
# Generate documentation
pnpm docs

# Preview documentation
pnpm docs:preview
```

## 🤝 Contributing

1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License. See the `LICENSE` file for details.

## 🔗 Useful Links

- [TypeDoc Documentation](./docs)
- [Styled Components](https://styled-components.com/)
- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
- [TypeScript](https://www.typescriptlang.org/)