Metadata-Version: 2.4
Name: uikitpr
Version: 0.3.2.post3142518377901
Summary: Complete visual framework with components, motion, and events for PyReact
Author-email: wanbnn <wanbnn@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/wanbnn/uikitpr
Project-URL: Documentation, https://uikitpr.readthedocs.io
Project-URL: Repository, https://github.com/wanbnn/uikitpr
Project-URL: Issues, https://github.com/wanbnn/uikitpr/issues
Keywords: pyreact,prpm,ui,css,utility-first,components,design-system
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyreact-framework>=1.0.5
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

<div align="center">

# UIKitPR

The utility-first visual framework built for PyReact.

[![PyPI](https://img.shields.io/pypi/v/uikitpr?logo=pypi&logoColor=white)](https://pypi.org/project/uikitpr/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://python.org)
[![PyReact](https://img.shields.io/badge/PyReact-1.0.5%2B-6D4AFF)](https://github.com/wanbnn/pyreact)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/wanbnn/uikitpr/blob/main/LICENSE)
[![Docs](https://readthedocs.org/projects/uikitpr/badge/?version=latest)](https://uikitpr.readthedocs.io/en/latest/)

Accessible components, themes, utility classes, and a native motion engine in
one Python package, with no mandatory Node pipeline.

**Website:** <https://wanbnn.github.io/uikitpr/>

</div>

## Why UIKitPR?

UIKitPR brings Tailwind-like composition and ready-made components to PyReact:

- predictable utility classes such as `flex`, `gap-4`, and `grid-cols-3`;
- Python components that return PyReact VNodes;
- light, dark, and custom themes powered by CSS variables;
- SSR, handlers, and properties compatible with PyReact's `h()`;
- CSS bundled in the wheel and exportable through the CLI;
- motion with springs, timelines, stagger, scroll, events, and lifecycle;
- fingerprinted web assets, manifests, updates, and Service Workers;
- loaders, skeletons, and ready-to-use visual states;
- text animations, animated backgrounds, marquees, and creative surfaces;
- a native 135-item creative catalog for PyReact;
- no JavaScript dependency or compilation step.

## Installation

```bash
prpm add uikitpr
```

You can also use `pip install uikitpr`.

## Quick start

```python
from uikitpr import Button, Card, CardBody, Heading, Stack, UIProvider


def App(props):
    return UIProvider(
        Card(
            CardBody(
                Stack(
                    Heading("Hello, PyReact!", level=1),
                    Button("Get started", variant="primary"),
                    gap=4,
                )
            )
        ),
        class_name="p-6",
        full_height=True,
    )
```

Components accept children directly or through
`h(Component, {"children": ...})`. The explicit `children` property is
important with current PyReact functional components.

## Utilities

Use classes in `className` or `class_name`:

```python
from uikitpr import Box, cx

Box(
    "Content",
    class_name=cx(
        "flex items-center gap-4 p-6 rounded shadow",
        {"bg-primary-soft": highlighted, "hidden": not visible},
    ),
)
```

The stylesheet includes flex/grid layout, spacing, sizing, typography, colors,
borders, shadows, and responsive variants such as `md-grid-cols-3`.

## Components

| Group | Components |
| --- | --- |
| Layout | `Box`, `Container`, `Stack`, `Grid`, `Divider` |
| Typography | `Heading`, `Text`, `Badge` |
| Actions | `Button`, `IconButton` |
| Forms | `Input`, `Textarea`, `Select`, `Checkbox`, `Switch` |
| Feedback | `Alert`, `Spinner`, `Progress`, `Modal` |
| Data and navigation | `Card`, `Table`, `Navbar`, `Breadcrumb`, `Avatar` |
| Creative effects | `BlurText`, `SplitText`, `GradientText`, `AuroraBackground`, `Marquee`, `SpotlightCard` |

Unconsumed properties are forwarded to the DOM VNode, including `onClick`,
`aria-*`, `data-*`, `style`, `id`, and `name`. See the
[component reference](https://uikitpr.readthedocs.io/en/latest/COMPONENTS.html).

## Themes

`UIProvider` includes the CSS and selects a theme:

```python
UIProvider(AppContent(), theme="dark", full_height=True)
```

Create a branded theme with tokens:

```python
from uikitpr import create_theme

brand = create_theme(
    "my-brand",
    primary="#ff006e",
    primary_hover="#d9005d",
    radius="1rem",
)

UIProvider(AppContent(), theme=brand)
```

## Motion and interaction

`UIProvider` includes the UIKitPR Motion runtime by default:

```python
from uikitpr import Motion, Spring, Transition

Motion(
    Card(...),
    preset="fade-up",
    trigger="in-view",
    while_hover={"transform": "translateY(-6px) scale(1.02)"},
    while_tap={"transform": "scale(.97)"},
    transition=Transition(
        duration=.7,
        spring=Spring(stiffness=170, damping=18),
    ),
)
```

The engine supports mount, in-view, click, hover, tap, focus, and scroll
animations; presets and custom keyframes; spring physics; staggered groups;
timelines; lifecycle events; declarative controls; dynamically added VNodes;
and `prefers-reduced-motion`. See the
[Motion guide](https://uikitpr.readthedocs.io/en/latest/MOTION.html).

## Creative effects

```python
from uikitpr import AuroraBackground, BlurText, Marquee, SpotlightCard

AuroraBackground(
    SpotlightCard(BlurText("Build something memorable", delay=.06)),
    color="#6d4aff",
    secondary="#26c6da",
)
```

The package includes animated text, backgrounds, borders, spotlights, and
continuous marquees, all configurable through Python props and compatible with
`prefers-reduced-motion`. Browse the live, copy-ready catalog on the
[GitHub Pages documentation](https://wanbnn.github.io/uikitpr/docs/).

### Complete creative catalog

The extended catalog covers 22 text animations, 28 interactive animations,
38 UI components, and 47 backgrounds. Import entries directly from `uikitpr`:

```python
from uikitpr import Aurora, ClickSpark, Dock, GlitchText
```

See the [complete list](docs/CREATIVE_CATALOG.md). The existing UIKitPR layout
`Stack` remains unchanged; the creative draggable stack is available as
`CreativeStack` or `uikitpr.creative.Stack`.

## Web cache and deployment

`CacheManager` writes SHA-256-fingerprinted assets, an inspectable manifest, and
a versioned Service Worker:

```python
from pathlib import Path
from uikitpr import CacheManager, CachePolicy, cache_script, motion_script, stylesheet

cache = CacheManager(
    Path("public"),
    policy=CachePolicy(name="my-app", version="2026.07.27"),
)
css = cache.add_text("uikitpr.css", stylesheet())
motion = cache.add_text("uikitpr-motion.js", motion_script())
runtime = cache.add_text("uikitpr-cache.js", cache_script())
cache.finalize(precache=["./"])
```

The browser exposes `window.UIKitPRCache.register()`, `refresh()`, `manifest()`,
`status()`, and `clear()`. See the
[cache guide](https://uikitpr.readthedocs.io/en/latest/CACHE.html).

## Loaders and visual states

```python
from uikitpr import OrbitLoader, Skeleton, SkeletonCard

OrbitLoader(size="lg")
Skeleton(lines=3)
SkeletonCard()
```

`DotsLoader`, `BarsLoader`, `RingLoader`, `PulseLoader`, `WaveLoader`, and
`PageLoader` are also available.

## External CSS and CSP

For strict Content Security Policy deployments, export and serve assets
separately:

```bash
uikitpr css -o static/uikitpr.css
uikitpr css -o static/uikitpr.min.css --minify
uikitpr motion -o static/uikitpr-motion.js
uikitpr creative -o static/uikitpr-creative.js
uikitpr cache -o static/uikitpr-cache.js
```

```python
from uikitpr import Styles

Styles(href="/static/uikitpr.css")
UIProvider(AppContent(), with_styles=False)
```

Client-only rendering also supports `Styles(inline=True, nonce="...")`.

## Development

```bash
prpm install
prpm test
prpm pack
prpm verify dist
```

The complete example is available in
[`examples/dashboard.py`](https://github.com/wanbnn/uikitpr/blob/main/examples/dashboard.py).
Build and serve the official
website with `prpm run site` and `prpm run serve`.

## Documentation

The complete English documentation is available on
[Read the Docs](https://uikitpr.readthedocs.io/en/latest/).

## License

MIT. See [LICENSE](https://github.com/wanbnn/uikitpr/blob/main/LICENSE).
