streamlit-flexnav 0.1.0__py3-none-any.whl

streamlit_flexnav/__init__.py

@@ -0,0 +1,10 @@
+"""
+streamlit-flexnav
+-----------------
+A navigation toolkit, menu schema, and Streamlit integration layer.
+"""
+from .ui.navigator import render_navigation
+
+__all__ = [
+    "render_navigation",
+]

streamlit_flexnav/cli.py

@@ -0,0 +1,2 @@
+def main():
+    print("FlexNav CLI is running")

streamlit_flexnav/configs/__init__.py

@@ -0,0 +1,2 @@
+# flexnav/configs/__init__.py
+# Generated: 2026-01-31 • Version 0.1.0

streamlit_flexnav/core/__init__.py

@@ -0,0 +1,2 @@
+# flexnav/core/__init__.py
+# Generated: 2026-01-31 • Version 0.1.0

streamlit_flexnav/core/loader.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+import structlog
+
+from streamlit_flexnav.core.settings import MENUPAGES_ROOT
+from streamlit_flexnav.core.models.menustruct import MenuStruct
+from streamlit_flexnav.core.models.menugroup import MenuGroup
+
+log = structlog.get_logger().bind(component="loader")
+
+
+def _load_module_from_path(path: Path):
+    spec = importlib.util.spec_from_file_location(path.stem, path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[path.stem] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_menupages() -> list[MenuStruct]:
+    """
+    Scan MENUPAGES_ROOT for .py files and extract PAGE = MenuStruct(...) definitions.
+    Folder structure is flattened into a single group name:
+        folder1/folder2/folder3 → "folder1_folder2_folder3"
+    """
+    results: list[MenuStruct] = []
+
+    for file in MENUPAGES_ROOT.rglob("*.py"):
+        if file.name.startswith("_"):
+            continue
+
+        try:
+            module = _load_module_from_path(file)
+
+            if not hasattr(module, "PAGE"):
+                log.warning("missing_PAGE_struct", file=str(file))
+                continue
+
+            page_struct = module.PAGE
+
+            if not isinstance(page_struct, MenuStruct):
+                log.error("invalid_PAGE_type", file=str(file))
+                continue
+
+            # Inject absolute path
+            page_struct.path = str(file.resolve())
+
+            # Compute flattened group name
+            relative = file.relative_to(MENUPAGES_ROOT)
+            parts = relative.parts[:-1]  # folders only
+
+            group = "_".join(parts) if parts else None
+            page_struct.group = group
+
+            results.append(page_struct)
+
+        except Exception as e:
+            log.exception("failed_loading_page", file=str(file), error=str(e))
+
+    log.info("menupages_loaded", count=len(results))
+    return results
+
+
+
+def load_menugroups() -> list[MenuGroup]:
+    """
+    Discover all MenuGroup definitions under MENUPAGES_ROOT.
+
+    Expected pattern inside each module:
+        MENU = MenuGroup(...)
+    """
+    results: list[MenuGroup] = []
+
+    for file in MENUPAGES_ROOT.rglob("*.py"):
+        if not file.name.startswith("__menu__"):
+            continue
+
+        try:
+            module = _load_module_from_path(file)
+
+            menu_struct = getattr(module, "MENU", None)
+            if menu_struct is None:
+                continue
+
+            if not isinstance(menu_struct, MenuGroup):
+                log.error("invalid_MENU_type", file=str(file))
+                continue
+
+            # Inject provenance
+            menu_struct.path = str(file.resolve())
+
+            results.append(menu_struct)
+
+        except Exception as e:
+            log.exception(
+                "failed_loading_menugroup",
+                file=str(file),
+                error=str(e),
+            )
+
+    log.info("menugroups_loaded", count=len(results))
+    return results
+

streamlit_flexnav/core/menuregistry.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import structlog
+from streamlit_flexnav.core.loader import load_menupages
+from streamlit_flexnav.ui.converter import MenuStruct
+
+log = structlog.get_logger().bind(component="menuregistry")
+
+
+class MenuRegistry:
+    """
+    Holds the loaded MenuStruct objects.
+    Reloadable, but not manually mutable.
+    """
+
+    def __init__(self):
+        self._items: list[MenuStruct] = []
+        self.reload()
+
+    def reload(self):
+        self._items = load_menupages()
+        log.info("menuregistry_reloaded", count=len(self._items))
+
+    def all(self) -> list[MenuStruct]:
+        return self._items
+
+
+# Singleton
+menuregistry = MenuRegistry()

streamlit_flexnav/core/models/__init__.py

@@ -0,0 +1,2 @@
+# flexnav/core/__init__.py
+# Generated: 2026-01-31 • Version 0.1.0

streamlit_flexnav/core/models/accesscontrol.py

@@ -0,0 +1,37 @@
+from typing import List
+from pydantic import BaseModel, Field, model_validator
+from .rolemode import RoleMode
+
+class AccessControl(BaseModel):
+    """
+    Role-based access control for a menu item.
+    Ensures no overlap between allowed and denied roles.
+    """
+
+    allowed_roles: List[RoleMode] = Field(
+        default_factory=list,
+        description="Roles that may see/use this menu item."
+    )
+    denied_roles: List[RoleMode] = Field(
+        default_factory=list,
+        description="Roles that must never see/use this menu item."
+    )
+
+    @model_validator(mode="after")
+    def validate_no_overlap(self):
+        overlap = set(self.allowed_roles) & set(self.denied_roles)
+        if overlap:
+            names = ", ".join(r.display_name() for r in overlap)
+            raise ValueError(f"Role(s) cannot be both allowed and denied: {names}")
+        return self
+
+    def is_allowed(self, role: RoleMode) -> bool:
+        """
+        Returns True if the given role is permitted.
+        Denied roles always override allowed roles.
+        """
+        if role in self.denied_roles:
+            return False
+        if self.allowed_roles and role not in self.allowed_roles:
+            return False
+        return True

streamlit_flexnav/core/models/linktarget.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+class LinkTarget(str, Enum):
+    self_ = "_self"
+    blank = "_blank"
+    parent = "_parent"
+    top = "_top"

streamlit_flexnav/core/models/menugroup.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import Optional, List
+
+
+class MenuGroup(BaseModel):
+    """
+    Represents a styled menu/submenu section.
+    This is NOT a page. It is a visual grouping.
+    """
+
+    key: str = Field(..., description="Unique group identifier")
+    label: str = Field(..., description="Displayed group label")
+
+    order: int = Field(
+        default=100,
+        ge=-10_000,
+        le=10_000,
+        description="Ordering in of menu",
+    )
+
+    # Styling
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    bold: bool = False
+    italic: bool = False
+    size: Optional[int] = None  # 1–3 simulated sizes
+
+    # Pages inside this group
+    pages: List[object] = Field(default_factory=list)

streamlit_flexnav/core/models/menustruct.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import List, Optional, Dict, Any, Annotated
+from pathlib import Path
+import re
+
+from pydantic import BaseModel, Field, HttpUrl, ConfigDict, field_validator
+from annotated_types import MinLen, MaxLen
+
+
+class MenuStruct(BaseModel):
+    """
+    Strict Pydantic v2 model for FlexNav 2.0 navigation entries.
+    Loader injects an absolute filesystem path into `.path`.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        str_strip_whitespace=True,
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+        frozen=False,   # loader injects .path
+    )
+
+    # ------------------------------------------------------------------
+    # Identity
+    # ------------------------------------------------------------------
+
+    key: Annotated[str, MinLen(2), MaxLen(64)] = Field(
+        ...,
+        pattern=r"^[a-z0-9][a-z0-9_-]{1,63}$",
+        description="Stable, unique key used as URL path",
+    )
+
+    label: Annotated[str, MinLen(1), MaxLen(80)] = Field(
+        ...,
+        description="Human-readable label for the sidebar",
+    )
+
+    group: Optional[Annotated[str, MinLen(1), MaxLen(64)]] = Field(
+        default=None,
+        description="Folder-based grouping injected by loader",
+    )
+    file: Path
+    order: int = Field(
+        default=100,
+        ge=-10_000,
+        le=10_000,
+        description="Ordering in the menu",
+    )
+
+    session_keys: Dict[str, object] = Field(
+        default_factory=dict,
+        description="Default session state keys for this page",
+    )
+
+    # ------------------------------------------------------------------
+    # Copy / UX
+    # ------------------------------------------------------------------
+
+    description: Optional[Annotated[str, MaxLen(280)]] = None
+    tooltip: Optional[Annotated[str, MaxLen(140)]] = None
+
+    # ------------------------------------------------------------------
+    # Navigation
+    # ------------------------------------------------------------------
+
+    path: Optional[str] = Field(
+        default=None,
+        description="Absolute filesystem path injected by loader",
+    )
+
+    url: Optional[HttpUrl] = None
+    is_default: bool = False
+
+    # ------------------------------------------------------------------
+    # State
+    # ------------------------------------------------------------------
+
+    enabled: bool = True
+    visible: bool = True
+    feature_flag: Optional[Annotated[str, MinLen(1), MaxLen(64)]] = None
+
+    # ------------------------------------------------------------------
+    # RBAC
+    # ------------------------------------------------------------------
+
+    required_role: str = Field(
+        default="none",
+        description="Role required to access this page",
+    )
+
+    # ------------------------------------------------------------------
+    # Presentation
+    # ------------------------------------------------------------------
+
+    icon: Optional[Annotated[str, MinLen(1), MaxLen(64)]] = None
+
+    tags: List[Annotated[str, MinLen(1), MaxLen(32)]] = Field(
+        default_factory=list,
+        description="Tags for search, filtering, or grouping",
+    )
+
+    shortcut: Optional[Annotated[str, MinLen(1), MaxLen(40)]] = None
+
+    # ------------------------------------------------------------------
+    # Hierarchy
+    # ------------------------------------------------------------------
+
+    children: List["MenuStruct"] = Field(default_factory=list)
+    parent: Optional[Annotated[str, MinLen(1), MaxLen(64)]] = None
+
+    # ------------------------------------------------------------------
+    # Extra metadata
+    # ------------------------------------------------------------------
+
+    telemetry: Dict[str, Any] = Field(default_factory=dict)
+    extra: Dict[str, Any] = Field(default_factory=dict)
+
+    # ------------------------------------------------------------------
+    # Validators
+    # ------------------------------------------------------------------
+
+    @field_validator("path")
+    @classmethod
+    def validate_absolute_path(cls, v: Optional[str]):
+        if v is None:
+            return v
+        p = Path(v)
+        if not p.is_absolute():
+            raise ValueError("path must be an absolute filesystem path")
+        return v
+
+    @field_validator("tags")
+    @classmethod
+    def dedupe_and_trim_tags(cls, v: List[str]):
+        out, seen = [], set()
+        for item in v:
+            t = item.strip()
+            if t and t not in seen:
+                out.append(t)
+                seen.add(t)
+        return out
+
+    @field_validator("key")
+    @classmethod
+    def enforce_key_format(cls, v: str):
+        if not re.match(r"^[a-z0-9_-]+$", v):
+            raise ValueError("key must match ^[a-z0-9_-]+$")
+        return v
+
+
+MenuStruct.model_rebuild()

streamlit_flexnav/core/models/rolemode.py

@@ -0,0 +1,25 @@
+from enum import IntEnum
+
+class RoleMode(IntEnum):
+    NONE = 0
+    VIEWER = 1
+    EDITOR = 2
+    KEYUSER = 3
+    ADMIN = 4  # highest privilege
+
+    def display_name(self) -> str:
+        return {
+            RoleMode.NONE: "None",
+            RoleMode.VIEWER: "Viewer",
+            RoleMode.EDITOR: "Editor",
+            RoleMode.KEYUSER: "Key User",
+            RoleMode.ADMIN: "Admin",
+        }[self]
+
+    @classmethod
+    def from_label(cls, label: str) -> "RoleMode":
+        normalized = label.strip().lower()
+        for role in cls:
+            if role.display_name().lower() == normalized:
+                return role
+        raise ValueError(f"Unknown role label: {label}")

streamlit_flexnav/core/settings.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+import yaml
+from pathlib import Path
+import structlog
+
+log = structlog.get_logger().bind(component="settings")
+
+
+# -------------------------------------------------------------------
+# ENVIRONMENT
+# -------------------------------------------------------------------
+
+ENV = os.getenv("FLEXNAV_ENV", "dev")
+CONFIG_FILE = Path(f"settings.{ENV}.yaml")
+
+
+# -------------------------------------------------------------------
+# CONFIG LOADING (OPTIONAL)
+# -------------------------------------------------------------------
+
+def _load_yaml_config(path: Path) -> dict:
+    """
+    Load YAML config if it exists.
+    If missing, return {} and log a warning.
+    """
+    if not path.exists():
+        log.warning("config_file_missing", path=str(path))
+        return {}
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception as e:
+        log.error("config_load_failed", path=str(path), error=str(e))
+        return {}
+
+
+RAW_CONFIG = _load_yaml_config(CONFIG_FILE)
+CONFIG = RAW_CONFIG.get("flexnav", {})
+
+
+# -------------------------------------------------------------------
+# SAFE DEFAULTS
+# -------------------------------------------------------------------
+
+# Default menupages root (library-safe)
+DEFAULT_MENUPAGES_ROOT = Path("app/menupages")
+
+# Allow override from YAML config
+MENUPAGES_ROOT = Path(CONFIG.get("menupages_root", DEFAULT_MENUPAGES_ROOT)).resolve()
+
+
+# -------------------------------------------------------------------
+# LOGGING
+# -------------------------------------------------------------------
+
+log.info(
+    "settings_loaded",
+    env=ENV,
+    config_file=str(CONFIG_FILE),
+    menupages_root=str(MENUPAGES_ROOT),
+)

streamlit_flexnav/images/__init__.py

@@ -0,0 +1,2 @@
+# flexnav/images/__init__.py
+# Generated: 2026-01-31 • Version 0.1.0

streamlit_flexnav/logging_setup.py

@@ -0,0 +1,59 @@
+import logging
+import sys
+from pathlib import Path
+import structlog
+
+from streamlit_flexnav.core.configs.admin_app_settings import load_admin_settings
+
+
+def configure_logging():
+    """
+    Configure structlog with optional file logging.
+    """
+
+    settings = load_admin_settings()
+    log_cfg = settings.flexnav.logging
+
+    handlers = []
+
+    # Console handler (always enabled)
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(logging.Formatter("%(message)s"))
+    handlers.append(console_handler)
+
+    # Optional file handler
+    if log_cfg.to_file:
+        file_path = Path(log_cfg.file_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler = logging.FileHandler(file_path, encoding="utf-8")
+        file_handler.setFormatter(logging.Formatter("%(message)s"))
+        handlers.append(file_handler)
+
+    logging.basicConfig(
+        level=getattr(logging, log_cfg.level.upper(), logging.INFO),
+        handlers=handlers,
+        format="%(message)s",
+    )
+
+    # Choose renderer
+    if sys.stdout.isatty():
+        renderer = structlog.dev.ConsoleRenderer()
+    else:
+        renderer = structlog.processors.JSONRenderer()
+
+    structlog.configure(
+        processors=[
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            getattr(logging, log_cfg.level.upper(), logging.INFO)
+        ),
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )

streamlit_flexnav/menupages/__menu__.py

@@ -0,0 +1,11 @@
+from streamlit_flexnav.core.models.menugroup import MenuGroup
+
+MENU = MenuGroup(
+    key="settings_settings_user",
+    label="Settings user",
+    order=0,
+    icon="📄",
+    color = "blue",
+    bold = False
+    italic = False,
+)    

streamlit_flexnav/menupages/settings/settings_admin.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from streamlit_flexnav.core.models.menustruct import MenuStruct
+import streamlit as st
+
+PAGE = MenuStruct(
+    key="settings_settings_admin",
+    label="Settings admin",
+    icon="📄",
+    order=0,
+    file=Path(__file__),
+    group=None,
+)
+
+def render():
+    st.title("Settings admin")
+    st.write("This page uses render() instead of main().")

streamlit_flexnav/menupages/settings/settings_user.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from streamlit_flexnav.core.models.menustruct import MenuStruct
+import streamlit as st
+
+PAGE = MenuStruct(
+    key="settings_settings_user",
+    label="Settings user",
+    icon="📄",
+    order=0,
+    file=Path(__file__),
+    group=None,
+)
+
+def render():
+    st.title("Settings user")
+    st.write("This page uses render() instead of main().")

streamlit_flexnav/tools/__init__.py

@@ -0,0 +1,2 @@
+# flexnav/core/__init__.py
+# Generated: 2026-01-31 • Version 0.1.0