Metadata-Version: 2.4
Name: verynicegui
Version: 1.0.4
Summary: A premium component-based SaaS framework built on top of NiceGUI
Author-email: Developer <developer@example.com>
Project-URL: Homepage, https://github.com/ilkermansur/verynicegui
Project-URL: Repository, https://github.com/ilkermansur/verynicegui.git
Project-URL: Bug Tracker, https://github.com/ilkermansur/verynicegui/issues
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. It automates layout structures, dynamic navigation menus, session authentication, role-based access control (RBAC), theme switching, multi-keyword data 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 Navigation 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.
* 📈 **Premium Analytics Charts (`VeryNiceChart`)**: High-performance charting supporting line, bar, pie, scatter, and area chart types using Apache ECharts or Highcharts engines, automatically styled with contrast coloring in dark mode.

---

## 📦 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 & VeryNiceChart)
└── data/
    └── users.json      # Built-in database file (automatically created on first run)
```

To run your application after scaffolding, execute:
```bash
python main.py
```

---

## 📐 12-Column Responsive Grid Layout

`verynicegui` uses a **12-column grid layout system** to structure pages neatly and responsively. 

All main components—`VeryNiceCard`, `VeryNiceTable`, and `VeryNiceChart`—include a `column` parameter which specifies how many columns (out of 12) the component should span.

For best results, wrap your components inside a `ui.grid(columns=12)` container:

```python
with ui.grid(columns=12).classes("w-full gap-4"):
    # Spans 4 columns (1/3 of the row width)
    VeryNiceCard(title="Active Subscriptions", body="1,420", column=4)
    VeryNiceCard(title="Monthly Revenue", body="$42,500", column=4)
    VeryNiceCard(title="Churn Rate", body="1.8%", column=4)
    
    # Spans 12 columns (Full width of the row)
    VeryNiceTable(table_name="Active Customers", columns=cols, rows=data, column=12)
```

**Common Span Values:**
* `column=12`: Full-width span (100% of row width)
* `column=6`: Half-width span (50% of row width)
* `column=4`: One-third span (33.3% of row width)
* `column=8`: Two-thirds span (66.6% of row width)

---

## 🛠️ 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` *(str)*: Title text. Shows smaller and grey in stats mode, bold and primary in content mode.
* `body` *(str, optional)*: Value string. Triggers immediate stats card formatting if provided.
* `column` *(int, optional)*: Width span in 12-column grids (e.g. `4` spans 1/3 of the row).
* `color` *(str, optional)*: Brand color for the decorative left border strip (e.g. `"#3b82f6"`, `"var(--mn-brand)"`).

---

### 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"}
    ]

    with ui.grid(columns=12).classes("w-full gap-4"):
        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=12,          # 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. `VeryNiceChart` (SaaS Analytics Chart)
Wraps charting engines inside styled containers that coordinate with page layouts and color themes.

#### A) Side-by-Side ECharts Dashboard
```python
from nicegui import ui
from verynicegui import VeryNiceChart
from main import app

@app.page("/sales/monthly", title="Monthly Performance", allowed_categories=["sales"])
def monthly_sales_page():
    months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    revenue = [12000, 15000, 18000, 14000, 22000, 26000]
    conversion = [2.1, 2.5, 2.8, 2.4, 3.2, 3.5]
    
    with ui.grid(columns=12).classes("w-full gap-4"):
        # Monthly Revenue Line Chart (Spans half of the grid)
        VeryNiceChart(
            title="Monthly Revenue (USD)",
            type="line",
            x_data=months,
            y_data=revenue,
            series_name="Revenue",
            column=6
        )
        
        # Monthly Conversion Rate Bar Chart (Spans other half)
        VeryNiceChart(
            title="Conversion Rate (%)",
            type="bar",
            x_data=months,
            y_data=conversion,
            series_name="Conversion %",
            column=6
        )
```

#### B) Custom Advanced Configuration (Apache ECharts)
```python
from verynicegui import VeryNiceChart

custom_opts = {
    "tooltip": {"trigger": "item"},
    "series": [{
        "name": "Traffic Sources",
        "type": "pie",
        "radius": ["40%", "70%"], # Donut chart
        "data": [
            {"value": 1048, "name": "Search Engine"},
            {"value": 735, "name": "Direct"},
            {"value": 580, "name": "Email"}
        ]
    }]
}

VeryNiceChart(
    title="Traffic Overview",
    options=custom_opts,
    column=12
)
```

**Parameters:**
* `options` *(dict, optional)*: Complete dictionary configuration for the underlying chart engine. If provided, `x_data` and `y_data` helpers are ignored.
* `column` *(int, optional)*: Width span in the 12-column grid layout (1-12 span).
* `engine` *(str, default 'echart')*: Underlying chart library. Supports:
  - `'echart'`: Uses Apache ECharts (fully open source, recommended).
  - `'highchart'`: Uses Highcharts (requires a commercial license).
* `type` *(str, default 'line')*: Easy helper type option. Supports:
  - `'line'`: Smooth line chart.
  - `'bar'`: standard bar columns.
  - `'pie'`: standard pie chart with flat labels and theme text colors.
  - `'scatter'`: Scatter plot markers.
  - `'area'`: Smooth line chart filled with bottom gradient shading.
* `title` *(str, optional)*: Bold card header title displayed above the chart canvas.
* `height` *(str, default '350px')*: Height specification in CSS dimensions.
* `x_data` *(list, optional)*: List of X-axis categories.
* `y_data` *(list, optional)*: List of Y-axis numeric values.
* `series_name` *(str, default 'Data')*: Label for the default data series.

---

### 6. `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).
