verynicegui 1.0.0__tar.gz

verynicegui-1.0.0/PKG-INFO

@@ -0,0 +1,278 @@
+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).

verynicegui-1.0.0/README.md

@@ -0,0 +1,267 @@
+# 🌟 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).

verynicegui-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "verynicegui"
+version = "1.0.0"
+description = "A premium component-based SaaS framework built on top of NiceGUI"
+readme = "README.md"
+authors = [
+    { name = "Developer", email = "developer@example.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "nicegui>=1.4.0",
+]
+
+[project.scripts]
+verynicegui-init = "verynicegui.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["verynicegui*"]

verynicegui-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

verynicegui-1.0.0/verynicegui/__init__.py

@@ -0,0 +1,31 @@
+from verynicegui.app import VeryNiceGUI
+from verynicegui.layout import VeryNiceLayout, RightDrawer
+from verynicegui.table import VeryNiceTable
+from verynicegui.card import VeryNiceCard
+from verynicegui.i18n import tr, set_language
+from verynicegui.auth import (
+    get_current_user,
+    is_admin,
+    has_permission,
+    do_login,
+    do_logout,
+    load_users,
+    save_users,
+)
+
+__all__ = [
+    "VeryNiceGUI",
+    "VeryNiceLayout",
+    "RightDrawer",
+    "VeryNiceTable",
+    "VeryNiceCard",
+    "tr",
+    "set_language",
+    "get_current_user",
+    "is_admin",
+    "has_permission",
+    "do_login",
+    "do_logout",
+    "load_users",
+    "save_users",
+]

verynicegui-1.0.0/verynicegui/__main__.py

@@ -0,0 +1,4 @@
+from verynicegui.cli import main
+
+if __name__ == "__main__":
+    main()