Metadata-Version: 2.4
Name: nativehtmlkit_ui
Version: 0.1.2
Summary: Development preview (not stable, not production-ready): minimal reactive UI toolkit for native HTML/CSS desktop applications
Author: NativeHTMLKit contributors
License: MIT
Project-URL: Homepage, https://nativehtmlkit.github.io/status/
Project-URL: Documentation, https://nativehtmlkit.github.io/
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nativehtmlkit<0.2.0,>=0.1.0
Dynamic: license-file

# nativehtmlkit_ui — Python UI toolkit

> **Development preview: not stable and not production-ready.** NativeHTMLKit development is
> currently focused on Core. This UI library is under development: its API can change without
> notice, it is not supported, and it should not be used for production work. For supported use,
> build on the [Python SDK](https://nativehtmlkit.github.io/sdk/python/) directly. Project status:
> <https://nativehtmlkit.github.io/status/>

Small reactive layouts and controls over the public
[nativehtmlkit Python SDK](https://pypi.org/project/nativehtmlkit/): native desktop windows
rendered from HTML/CSS by the NativeHTMLKit host, with no browser and no JavaScript. Python
3.10+, NativeHTMLKit SDK 0.1.x, Linux (KDE Plasma Wayland) and Windows.

```bash
uv init --app myapp && cd myapp     # a project for your app (https://docs.astral.sh/uv/)
uv add nativehtmlkit_ui
uv run app.py
```

**Version 0.1.2 is a development preview.** It changes only this notice and the package links;
the code is the same as 0.1.1.

```python
from nativehtmlkit import Application
from nativehtmlkit_ui import UI, computed, state

with Application.start(name="Hello UI") as app:
    name = state("Ada")
    greeting = computed(lambda: f"Hi, {name.value or 'stranger'}!")
    ui = UI(title="Hello", theme="cobalt", density="compact")
    with ui.column():
        ui.heading("Hello")
        ui.input(name, label="Name")
        ui.text(greeting)
        ui.button("Clear", variant="secondary", on_click=lambda event: name.set(""))
    ui.mount(app)
    app.run()
```

- **State in, window out.** `state()` holds data, `computed()` derives values, components bind
  to either, and event handlers only change state. Updates are batched into document commands.
- **Components:** `row`, `column`, `grid` (responsive), `card`, `stack`, `heading`, `text`,
  `badge`, `alert`, `button`, `input`, `checkbox`, `select`, `when` (conditional region),
  `text_list`, plus `element` and trusted `raw_html` for custom markup.
- **Threads:** each window has its own UI owner thread; worker threads hand results over with
  `ui.post()`.
- **Themes:** `cobalt`, `graphite`, `daylight`; densities `compact`, `regular`, `comfortable`;
  your own CSS via `extra_css`.

Dialogs, the clipboard, live bitmaps and window management are SDK features you call next to
the UI. Known open defects: concurrent updates to one `Computed` from several threads
and accumulating shutdown callbacks with many mount cycles.

## Documentation

The UI library's documentation and source are not public while it is in development. The SDK it
builds on is documented at <https://nativehtmlkit.github.io/>.
