Metadata-Version: 2.4
Name: streamlit-flexnav
Version: 2.0.0
Summary: A modular, RBAC-aware navigation framework for Streamlit applications.
Author-email: Nednaz-IT <informatie@nednazit.nl>
License: MIT
Project-URL: Homepage, https://github.com/informatie/streamlit-flexnav
Project-URL: Documentation, https://github.com/informatie/streamlit-flexnav/wiki
Project-URL: Source, https://github.com/informatie/streamlit-flexnav
Project-URL: Issues, https://github.com/informatie/streamlit-flexnav/issues
Keywords: streamlit,navigation,rbac,menu,ui-framework,app-framework
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.54
Requires-Dist: pydantic>=2.12.5
Requires-Dist: structlog>=25.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.21.1
Requires-Dist: rich>=13.7
Requires-Dist: pandas>=2.2
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: cryptography>=46.0.5
Requires-Dist: sqlalchemy>=2.0.46
Requires-Dist: importlib>=1.0.4
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: black>=24.1; extra == "dev"
Dynamic: license-file



# 1. streamlit‑flexnav

`streamlit-flexnav` is a **modular, folder‑driven navigation framework** for Streamlit applications.  
It automatically builds menus from your project structure and lets you extend them with metadata, icons, colors, RBAC, and custom behavior.

The project is actively evolving.  
The first stable release will be **v2.0.0**.

- [1. streamlit‑flexnav](#1-streamlitflexnav)
- [1.1. ✨ Features](#11--features)
- [1.2. 📦 Installation](#12--installation)
- [1.3. 🚀 Quick Start](#13--quick-start)
- [1.4. 🧭 Navigation Behavior](#14--navigation-behavior)
- [1.5. ⚙️ Configuration](#15-️-configuration)
- [1.6. 🧭 Example: `__menu__.py` (Menu Settings)](#16--example-__menu__py-menu-settings)
- [1.7. 📄 Example: Page Settings (inside a page module)](#17--example-page-settings-inside-a-page-module)
  - [1.7.1. Example 1](#171-example-1)
  - [1.7.2. Example 2](#172-example-2)
- [1.8. 🧩 Page Template Generator (FlexNav 2.0)](#18--page-template-generator-flexnav-20)
- [1.9. 🛠 CLI Tools](#19--cli-tools)
- [1.10. 📁 Project Structure](#110--project-structure)
- [1.11. 🧪 Development](#111--development)
- [1.12. 📄 License](#112--license)
- [1.13. ⭐ Acknowledgements](#113--acknowledgements)


---

# 1.1. ✨ Features

- **Folder‑driven navigation** — menus are generated from your directory structure  
- **Schema‑driven metadata** — configure menus and pages using `__menu__.py` and `PageStruct`  
- **Automatic UI rendering** — FlexNav handles menu rendering, active state, and routing  
- **Role‑based access control (RBAC)** — restrict menus and pages by user roles  
- **Icons, colors, ordering, and collapsible groups**  
- **CLI tools** for inspection, linting, debugging, and scaffolding  
- **Plugin‑friendly architecture**  
- **Fast, reproducible builds** using `uv`  

---

# 1.2. 📦 Installation

Install from PyPI:

```bash
pip install streamlit-flexnav
```

Or using `uv`:

```bash
uv add streamlit-flexnav
```

---

# 1.3. 🚀 Quick Start

See the full quickstart guide:

```
QUICKSTART.md
```

---

# 1.4. 🧭 Navigation Behavior

FlexNav automatically:

- Builds menu groups and pages from your folder structure  
- Applies RBAC rules  
- Highlights the active page  
- Supports icons, dividers, and collapsible groups  
- Integrates with Streamlit session state  
- Orders menus and pages using `order` metadata  

---

# 1.5. ⚙️ Configuration

FlexNav uses a unified configuration file:

See (QUICKSTART.md) for more information.
```
configs/admin/flexnav_config.yaml
```

Example:

```yaml
flexnav:
  menupages: "demo_pages"
  env: "dev"

  authentication:
    mode: "none"
    local:
      users_file: "configs/users.yaml"

oauth:
  enabled: false
  provider: "google"
  client_id: ""
  client_secret: ""
  redirect_uri: "http://localhost:8501"
  scopes:
    - "openid"
    - "email"
    - "profile"

logging:
  to_file: false
  file_path: "logs"
  level: "INFO"
```

---

# 1.6. 🧭 Example: `__menu__.py` (Menu Settings)

Place this file inside any folder that represents a menu group.  
FlexNav loads it automatically.

```python
# __menu__.py
from streamlit_flexnav import MenuStruct

menu = MenuStruct(
    label="Sales Dashboard",
    order=20,
    icon="📊",
    color="#1E88E5",
    required_roles=["sales"],
    collapsed=True,
    description="KPIs, reports, and analytics for the sales team.",
)
```

This produces:

- A menu group labeled **Sales Dashboard**  
- Sorted after groups with lower order  
- Visible only to users with the `sales` role  
- Styled with icon + color  
- Collapsed by default  
- All pages inside the folder inherit this group  

---

# 1.7. 📄 Example: Page Settings (inside a page module)

Each page is a Python file.  
FlexNav reads the metadata from a `page()` function and uses `render()` to draw the UI.

## 1.7.1. Example 1

```python
import streamlit as st
from streamlit_flexnav.core.models.pagestruct import PageStruct

def page():
    return PageStruct(
        label="Finance",
        icon="🎨",
        order=2,
        required_roles=[],
        is_default=False,
        path=__file__,
    )

def render():
    st.title("Finance")
    st.write("You are on: finance")
```

## 1.7.2. Example 2

```python
import streamlit as st
from streamlit_flexnav.core.models.pagestruct import PageStruct

def page():
    return PageStruct(
        label="Customer Overview",
        icon="📊",
        order=5,
        required_roles=["sales"],
        is_default=True,
        description="Overview of customer KPIs and segmentation.",
        path=__file__,
    )

def render():
    st.title("Customer Overview")
    st.write("This page shows customer KPIs and segmentation charts.")
```

---

# 1.8. 🧩 Page Template Generator (FlexNav 2.0)

A helper function for generating new pages:

```python
def generate_page_template(path: str, label: str, icon: str = "📄", order: int | None = None):
    import os
    from textwrap import dedent

    os.makedirs(os.path.dirname(path), exist_ok=True)

    template = dedent(f"""
        import streamlit as st
        from streamlit_flexnav.core.models.pagestruct import PageStruct

        def page():
            return PageStruct(
                label="{label}",
                icon="{icon}",
                order={order if order is not None else "None"},
                path=__file__,
            )

        def render():
            st.title("{label}")
            st.write("This is the {label} page.")

        if __name__ == "__main__":
            render()
    """).strip() + "\n"

    with open(path, "w", encoding="utf-8") as f:
        f.write(template)

    return path
```

---

# 1.9. 🛠 CLI Tools

After installation, the CLI becomes available:

```
flexnav
```

Commands:

```
config   FlexNav configuration tools
menu     Menu inspection tools
menuviz  Visualize and inspect FlexNav menu structure
pages    Page inspection tools
lint     FlexNav linter
doctor   FlexNav health checks
setup    Create a new FlexNav application structure
debug    Debugging tools
```

Each command provides its own help:

```bash
flexnav doctor --help
```

---

# 1.10. 📁 Project Structure

```
src/streamlit_flexnav/
  core/          # Loaders, runtime models, RBAC, ordering logic
  ui/            # Streamlit UI components
  tools/         # CLI tools
```

See `API_REFERENCE.md` for full details.

---

# 1.11. 🧪 Development

Clone the repository:

```bash
git clone https://github.com/informatie/streamlit-flexnav
cd streamlit-flexnav
```

Set up the environment:

```bash
uv venv
uv sync
source .venv/bin/activate
```

---

# 1.12. 📄 License

MIT License — see `LICENSE` for details.

---

# 1.13. ⭐ Acknowledgements

FlexNav is actively evolving.  
Upcoming enhancements include:

- RBAC improvements  
- Folder and page validation  
- Drag‑and‑drop menu/page ordering  
- Admin UI for editing menu and page settings  
- File system watcher for live reload  
- SSO and OAuth integrations  
- User‑defined menu settings  

---
