Metadata-Version: 2.4
Name: verynicegui
Version: 1.0.0
Summary: A premium component-based SaaS framework built on top of NiceGUI
Author-email: Developer <developer@example.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: nicegui>=1.4.0

# 🌟 verynicegui

A premium, component-based SaaS boilerplate framework built on top of **NiceGUI**. 

`verynicegui` empowers developers to focus entirely on building business logic and page content, automating layout structures, dynamic navigations, session authentication, role-based access control (RBAC), theme switching, multi-keyword tables, and seamless i18n localizations.

---

## 🚀 Key Features

* 🛡️ **Out-of-the-Box Session Auth & RBAC**: Session-based login/logout guards with category-based page access checks.
* 📱 **Premium Responsive Layout (`VeryNiceGUI` / `VeryNiceLayout`)**: Complete SaaS layout including a Header, dynamic Left Drawer, Footer, and interactive Right Detail Drawer.
* 🌍 **Zero-Flash Theme & i18n Switching**: Anti-flash dynamic HTML theme classes and quick "TR / EN" segment button toggle in the drawer.
* 🏗️ **One-Command CLI Scaffolding**: Setup your entire project directory and files instantly using the built-in CLI.
* 📊 **Enhanced Data Table (`VeryNiceTable`)**: Paging bounds (`max_row`), custom 12-column spans, row click triggers, and comma/space separated multi-keyword AND-logic search.
* 🎴 **Justified Typography Cards (`VeryNiceCard`)**: Standalone stat cards or context manager wrapper cards with dynamic border strips and justified block text.

---

## 📦 Installation

To install `verynicegui` in your environment, run the following command:

```bash
pip install verynicegui
```

*(For local/editable development)*:
```bash
pip install -e . --break-system-packages
```

---

## 🏗️ Quick Project Scaffold (CLI)

Get a fully structured, modular SaaS project up and running in seconds. Open an empty folder in your terminal and run:

```bash
verynicegui-init
```

or alternatively:

```bash
python -m verynicegui
```

### Generated Project Structure:
```text
my_saas_app/
│
├── main.py             # App settings, Header, Footer, Drawer configuration & Launcher
├── translations.py     # Separate dictionary file for multi-language terms
├── assets/             # Holds static files (e.g. logos, graphics)
│   └── logo.svg        # Default premium SVG logo
├── pages/              # Directory for modular page layouts
│   ├── __init__.py     # Exports all pages
│   ├── home.py         # Home page module
│   └── sales.py        # Sales page module (featuring VeryNiceTable)
└── data/
    └── users.json      # Built-in database file (automatically created on first run)
```

---

## 🛠️ API & Component Reference

### 1. `VeryNiceGUI` (App Configuration)
Used in `main.py` to bootstrap the application drawer, header, footer, static assets, and localization parameters.

```python
# main.py
import sys
# Alias the entrypoint namespace as 'main' to prevent duplicate execution during circular imports
sys.modules['main'] = sys.modules[__name__]

from verynicegui import VeryNiceGUI
from translations import TRANSLATIONS

app = VeryNiceGUI(
    title="My SaaS App",
    header={
        "logo": "assets/logo.svg",  # SVG/PNG file path or Material Icon name
        "title": "SaaSApp",
        "show_theme_toggle": True
    },
    left_drawer={
        "title": "Navigation Menu",
        "menu": [
            {"category": "home", "title": "Home", "icon": "home", "route": "/"},
            {
                "category": "sales", 
                "title": "Sales", 
                "icon": "payments",
                "subcategories": [
                    {"title": "Daily", "route": "/sales/daily", "icon": "today"},
                    {"title": "Monthly", "route": "/sales/monthly", "icon": "calendar_month"}
                ]
            }
        ]
    },
    footer={
        "left": "© 2026 SaaSApp Inc.",
        "middle": "All Rights Reserved",
        "right": "System Status: Online"
    },
    translations=TRANSLATIONS
)

import pages

if __name__ in {"__main__", "__mp_main__"}:
    app.run(port=8080)
```

---

### 2. `@app.page` (Route & Guard Decorator)
Registers routes and applies RBAC categories to restrict pages to authorized users.

```python
# pages/home.py
from nicegui import ui
from verynicegui import get_current_user, tr
from main import app

# Restricts this page to users having the 'home' category permission
@app.page("/", title="Home Page", allowed_categories=["home"])
def home_page():
    user = get_current_user()
    display_name = user.get("display_name") if user else "Guest"
    
    ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))
```

---

### 3. `VeryNiceCard` (Justified Content Cards)
A premium card container. Can be instantiated on a single line or as a context manager block.

#### A) Single-line Statistic Card
```python
from verynicegui import VeryNiceCard

VeryNiceCard(title="Total Revenue", body="$124,500", column=4)
```

#### B) Context Manager Block Card
```python
from verynicegui import VeryNiceCard
from nicegui import ui

with VeryNiceCard(title="Important Announcement", column=12, color="var(--mn-brand)"):
    ui.label("This paragraph text inside the card is automatically justified (aligned left and right).")
    ui.button("Read More")
```

**Parameters:**
* `title`: Title text. Shows smaller and grey in stats mode, bold and primary in content mode.
* `body` *(Optional)*: Value string. Triggers immediate stats card formatting if provided.
* `column` *(Optional)*: Width span in 12-column grids (e.g. `4` spans 1/3 of the row).
* `color` *(Optional)*: Brand color for the decorative left border strip (e.g. `"#3b82f6"`, `"red"`).

---

### 4. `VeryNiceTable` (Advanced Paginated Grid)
Features scrollable headers, page pagination, multi-keyword search parsing, and custom action callbacks.

```python
# pages/sales.py
from nicegui import ui
from verynicegui import VeryNiceTable, tr
from main import app

@app.page("/sales/daily", title="Daily Sales", allowed_categories=["sales"])
def daily_sales_page(drawer):
    transactions = [
        {"id": "#1001", "product": "Pro License", "amount": "99 USD", "desc": "Premium subscription key"},
        {"id": "#1002", "product": "Enterprise Setup", "amount": "1200 USD", "desc": "Custom server migration consulting"}
    ]

    VeryNiceTable(
        table_name="Transactions",
        columns=[
            {"name": "id", "label": "ID", "field": "id", "align": "left"},
            {"name": "product", "label": "Product", "field": "product", "align": "left"},
            {"name": "amount", "label": "Amount", "field": "amount", "align": "right"}
        ],
        rows=transactions,
        max_row=5,          # Maximum rows per page before paginating
        column=8,           # Span in the 12-column parent layout
        font_size="m",      # Options: 's', 'm', 'l'
        font_family="Outfit", # Options: 'Outfit', 'Inter'
        on_row_click=lambda row: drawer.toggle(row["desc"]) # Drawer action on row click
    )
```

#### 🔍 Multi-Keyword Search AND Filter
The search box supports multiple keyword arguments separated by **spaces** (` `) or **commas** (`,`). For example, searching for `Pro Premium` matches records containing *both* "Pro" and "Premium".

---

### 5. `RightDrawer` (Details sidebar)
To instantiate the interactive right drawer, declare a parameter named `drawer` or `right_drawer` in your page function. The decorator will automatically inject the drawer.

```python
# drawer control commands:
drawer.open("Content String or callback")
drawer.close()
drawer.toggle("Details info here...") # Toggles open if closed, or updates current drawer content
```

---

## 🌍 Localization & Multi-Language (i18n)

Define translation mappings in `translations.py` and supply them to `VeryNiceGUI`.

### `translations.py` Schema:
```python
TRANSLATIONS = {
    "tr": {
        "welcome": "Hoş geldiniz, {name}! 👋",
        "home_title": "Ana Sayfa",
        "btn_save": "Kaydet"
    },
    "en": {
        "welcome": "Welcome, {name}! 👋",
        "home_title": "Home Page",
        "btn_save": "Save"
    }
}
```

### Usage:
Use the `tr` helper function inside pages to fetch translations for the user's active language choice.
```python
from verynicegui import tr

# Simple translate
ui.label(tr("btn_save", "Save"))

# Formatted dynamic translate
ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))
```

---

## 🔑 Authentication Database (`data/users.json`)

On the first application launch, the directory `data/` and `users.json` are created automatically. It contains default accounts:

* **Admin** (`username: admin`, `password: admin123`) -> Full access to all categories and `/admin` user management panels.
* Custom accounts can be registered and configured with page access permissions directly via the Admin panel.

---

## 🎨 Theme & Styles Override

Style overrides and color schemas are defined inside CSS variables in [verynicegui/layout.py](file:///Users/ilkermansur/Desktop/nice_agent/verynicegui/layout.py):

* `--mn-bg`: Master app background color.
* `--mn-header-bg`: Header navbar color.
* `--mn-drawer-bg`: Navigation sidebar color.
* `--mn-card-bg`: Card container background.
* `--mn-brand`: Brand indicator color (defaults to indigo purple).
