smarty-ui 0.1.2
A reusable UI component library built on pydivkit
Requires Python: >=3.13

# Smarty UI

A UI components framework for building DivKit widgets for Smarty, aligned with the Smartbank Figma design system.

## Overview

Smarty UI provides a layered component architecture built on top of [pydivkit](https://github.com/divkit/divkit):

- **Tokens** - Design system values (colors, typography, spacing)
- **Primitives** - Basic UI atoms (text, buttons, images, dividers)
- **Composites** - Reusable molecules (badges, input fields, status bubbles)
- **Blocks** - Complete UI patterns (cards, lists, widgets)

## Installation

```bash
pip install -e .
```

## Quick Start

```python
import pydivkit as dk
from smart_ui import (
    # Layout helpers
    HStack, VStack,
    # Primitives
    title_1, text_1, primary_button, smarty_button,
    # Blocks
    transaction_success_widget, payment_status_widget,
    home_balance_widget,
    # Theme
    default_theme,
)

# Create a simple card
card = VStack(
    [
        title_1("Hello, Smarty!"),
        text_1("Welcome to the UI framework."),
        primary_button("Get Started", action_url="div-action://start"),
    ],
    gap=12,
    padding=16,
    background="#FFFFFF",
    corner_radius=12,
)

# Create a transaction status widget
widget = transaction_success_widget(
    amount="200 000",
    recipient="ALEKSANDR GURYANOV ** 2221",
    date_time="3 сентября 2023 18:27",
)
```

## Components

### Layout Helpers

```python
# Horizontal stack (row)
HStack([item1, item2, item3], gap=8, align_v="center")

# Vertical stack (column)  
VStack([header, content, footer], gap=12, align_h="left", padding=16)
```

### Primitives

| Component | Description |
|-----------|-------------|
| `title_1`, `title_2` | Heading text styles |
| `text_1`, `text_2`, `text_3` | Body text styles |
| `caption_1`, `caption_2`, `caption_3` | Small text styles |
| `primary_button`, `secondary_button` | Button variants |
| `outline_button`, `smarty_button` | Outline button styles |
| `icon`, `avatar`, `cover_image` | Image components |
| `divider`, `h_spacer`, `v_spacer` | Layout utilities |

### Composites

| Component | Description |
|-----------|-------------|
| `status_bubble` | Transaction/payment status display |
| `chat_bubble` | Chat message bubbles |
| `badge`, `outline_badge` | Label badges |
| `icon_label` | Icon + text pair |
| `input_field` | Text input field |
| `card_balance_item` | Card balance row |

### Blocks

| Component | Description |
|-----------|-------------|
| `transaction_success_widget` | Successful transfer status |
| `transaction_failed_widget` | Failed transfer status |
| `transaction_pending_widget` | Pending transfer status |
| `payment_success_widget` | Successful payment status |
| `payment_failed_widget` | Failed payment status |
| `payment_pending_widget` | Pending payment status |
| `home_balance_widget` | Utility balances widget |
| `balance_widget` | Card/account balances |
| `bank_card` | Bank card display |
| `service_list` | Service categories list |
| `contacts_list` | Contact list |

## Theming

```python
from smart_ui import default_theme, dark_theme, Theme, ColorTokens

# Use default Smartbank theme
widget = balance_widget(total_balance="1 000 000", theme=default_theme)

# Use dark theme
widget = balance_widget(total_balance="1 000 000", theme=dark_theme)

# Create custom theme
custom_theme = Theme(
    colors=ColorTokens(
        primary="#FF5722",
        background="#FAFAFA",
    )
)
```

## Project Structure

```
src/smart_ui/
├── tokens/           # Design tokens
│   ├── colors.py     # Color palette
│   ├── typography.py # Font styles
│   └── spacing.py    # Spacing scale
├── primitives/       # Basic UI atoms
│   ├── text.py       # Text components
│   ├── button.py     # Button variants
│   ├── image.py      # Image components
│   └── smarty_button.py
├── composites/       # Reusable molecules
│   ├── status_bubble.py
│   ├── chat_bubble.py
│   └── ...
├── blocks/           # Complete UI patterns
│   ├── transaction_status_widget.py
│   ├── payment_status_widget.py
│   ├── home_balance_widget.py
│   └── ...
└── _helpers.py       # Layout utilities (HStack, VStack)
```

## License

Internal use only.