Metadata-Version: 2.4
Name: tkblocks
Version: 0.1.2
Summary: A scrollable, collapsible section-based content renderer for tkinter.
Author-email: Konstantinos Katsos <konstan.katsos@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kon-katsos/tkblocks
Project-URL: Repository, https://github.com/kon-katsos/tkblocks
Project-URL: Issues, https://github.com/kon-katsos/tkblocks/issues
Keywords: tkinter,gui,widgets,collapsible,sections
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=9.0
Requires-Dist: pydantic>=2.0
Provides-Extra: yaml
Requires-Dist: pyyaml; extra == "yaml"
Provides-Extra: requests
Requires-Dist: requests; extra == "requests"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# tkblocks ![Project Status](https://img.shields.io/badge/status-alpha-orange)

A scrollable, collapsible section-based content renderer for tkinter.

Drop-in collapsible section panels for tkinter apps — load content from 
Python, JSON, YAML, or TOML.

tkblocks is a simple, tested and predictable tkinter implementation that complies 
with your app's existing theme and style.

- Import tkblocks
- Pass a notebook tab or plain frame.
- Provide content with json, yaml, toml or python API.

**Useful for:**
- FAQ panels
- Changelogs / release notes
- Settings/help dialogs
- Onboarding flows
- Dashboards with collapsible read-only data sections
- Debug/log viewers

## Installation

```bash
pip install tkblocks
```

Optional dependencies based on content types used:

```bash
pip install pyyaml    # for .yaml/.yml content files
pip install requests  # for WebImageContent
```

## Usage

### Python API

```python
from tkblocks import Blocks, SectionData, TextContent, LinkContent, LocalImageContent

sections = [
    SectionData(
        title="Getting Started",
        contents=[
            TextContent(text="Welcome to the app."),
            LinkContent(text="Documentation", url="https://example.com"),
        ],
    ),
    SectionData(
        title="Resources",
        contents=[
            LocalImageContent(text="Overview", path="media/overview.png"),
        ],
    ),
]

blocks = Blocks(parent, sections_data=sections, title="📖 User Guide")
blocks.pack(fill="both", expand=True)
```

### Loading from file

```python
from tkblocks import Blocks, load_sections

blocks = Blocks(parent, sections_data=load_sections("guide.toml"), title="📖 User Guide")
blocks.pack(fill="both", expand=True)
```

Supported formats: `.json`, `.yaml`, `.yml`, `.toml`

### Example TOML file

```toml
[[sections]]
title = "Getting Started"

[[sections.contents]]
type = "text"
text = """
Welcome to the app.
This is a multiline description.
"""

[[sections.contents]]
type = "link"
text = "Documentation"
url = "https://example.com"

[[sections]]
title = "Resources"

[[sections.contents]]
type = "local_image"
text = "Overview diagram"
path = "media/overview.png"
```

## Importing

Always import from the top-level package:
```python
from tkblocks import Blocks, load_sections  # ✅
from tkblocks.blocks import Blocks          # ❌ not guaranteed stable
```

## Content block types

| Type | Class | Required fields |
|---|---|---|
| Plain text | `TextContent` | `text` |
| Copyable text | `CopyableContent` | `text` |
| Hyperlink | `LinkContent` | `text`, `url` |
| Local image | `LocalImageContent` | `path` |
| Web image | `WebImageContent` | `url` |

## Requirements

- Python >= 3.11
- Pillow
- Pydantic

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
