flask-construct-ui 0.9.5__py3-none-any.whl

flask_construct_ui/base.py

@@ -0,0 +1,1259 @@
+from __future__ import annotations
+import inspect
+import json
+from os import path
+from functools import wraps
+import logging
+from importlib.metadata import entry_points
+
+logger = logging.getLogger("flask_construct_ui")
+
+from flask import (
+    Flask,
+    Blueprint,
+    render_template,
+    send_from_directory,
+    request,
+    url_for,
+    current_app,
+    Response,
+    stream_with_context,
+    g,
+)
+from markupsafe import Markup
+from .language import Translator, set_language_from_browser
+from typing import Callable, Optional
+from .components import (
+    Component,
+    components,
+    Field,
+    LiveComponent,
+    ChartComponent,
+    CalendarComponent,
+    TabsComponent,
+    FormComponent,
+    jinja_env,
+)
+from .sanitize import sanitize_html
+from .headless import live_container, live_attributes
+from .navigation import resolve_next
+from .icons import render_icon
+
+
+from .csrf import (
+    CSRF_SESSION_KEY,
+    CSRF_FORM_FIELD,
+    CSRF_HEADER,
+    CSRF_UNSAFE_METHODS,
+    generate_csrf_token,
+    csrf_field,
+    validate_csrf_token,
+)
+from .pagination import (
+    DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE,
+)
+
+
+def list_action(name, icon):
+    def decorator(f):
+        f._list_action_info = {"name": name, "icon": icon}
+        return f
+
+    return decorator
+
+
+def tab_action(name, icon):
+    def decorator(f):
+        f._tab_action_info = {"name": name, "icon": icon}
+        return f
+
+    return decorator
+
+
+def edit_action(name, icon):
+    def decorator(f):
+        f._edit_action_info = {"name": name, "icon": icon}
+        return f
+
+    return decorator
+
+
+def expose(url="/", methods=None):
+    def wrap(f):
+        if not hasattr(f, "_urls"):
+            f._urls = []
+        if methods is None:
+            match f.__name__.lower():
+                case "patch":
+                    method = ("PATCH",)
+                case "delete":
+                    method = ("DELETE",)
+                case "post":
+                    method = ("POST",)
+                case _:
+                    method = ("GET",)
+        else:
+            method = methods
+        f._urls.append((url, method))
+        return f
+
+    return wrap
+
+
+def datasource(name=None):
+    def wrap(f):
+        f._datasource_name = name or f.__name__
+        return f
+
+    return wrap
+
+
+SSE_DONE = "done"
+
+
+def livesource(name=None, interval=10):
+    def wrap(f):
+        f._livesource_name = name or f.__name__
+        f._livesource_interval = interval
+        return f
+
+    return wrap
+
+
+# Base views
+def _wrap_view(f):
+    # Avoid wrapping view method twice
+    if hasattr(f, "_wrapped"):
+        return f
+
+    @wraps(f)
+    def inner(self, *args, **kwargs):
+        # Store current admin view
+        # h.set_current_view(self)
+
+        return self._run_view(f, *args, **kwargs)
+
+    inner._wrapped = True
+
+    return inner
+
+
+class PageMeta(type):
+    def __init__(cls, classname, bases, fields):
+        type.__init__(cls, classname, bases, fields)
+
+        cls._curls = []
+        cls._default_view = None
+        cls.list_actions = []
+        cls.tab_actions = []
+        cls.edit_actions = []
+        cls._datasources = {}
+        cls._livesources = {}
+        cls._auth_rules = {}
+
+        for p in dir(cls):
+            attr = getattr(cls, p)
+
+            if hasattr(attr, "_datasource_name"):
+                cls._datasources[attr._datasource_name] = p
+
+            if hasattr(attr, "_livesource_name"):
+                cls._livesources[attr._livesource_name] = (p, attr._livesource_interval)
+
+            if hasattr(attr, "_construct_auth"):
+                cls._auth_rules[p] = attr._construct_auth
+
+            if hasattr(attr, "_urls"):
+                # Collect methods
+                for url, methods in attr._urls:
+                    cls._curls.append((url, p, methods))
+
+                    if url == "/":
+                        cls._default_view = p
+
+                    if hasattr(attr, "_list_action_info"):
+                        info = attr._list_action_info
+                        cls.list_actions.append(
+                            {
+                                "endpoint": p,
+                                "name": info["name"],
+                                "icon": info["icon"],
+                                "url": url,
+                            }
+                        )
+
+                    if hasattr(attr, "_tab_action_info"):
+                        info = attr._tab_action_info
+                        cls.tab_actions.append(
+                            {
+                                "endpoint": p,
+                                "name": info["name"],
+                                "icon": info["icon"],
+                                "url": url,
+                            }
+                        )
+
+                    if hasattr(attr, "_edit_action_info"):
+                        info = attr._edit_action_info
+                        cls.edit_actions.append(
+                            {
+                                "endpoint": p,
+                                "name": info["name"],
+                                "icon": info["icon"],
+                                "url": url,
+                            }
+                        )
+
+                # Wrap views
+                setattr(cls, p, _wrap_view(attr))
+
+
+class PageBase(metaclass=PageMeta):
+    url = None
+    name = None
+    # Semantic icon name resolved per icon mode (see icons.ICONS). Apps may
+    # override with their own semantic name or a raw icon string.
+    icon = "page"
+    endpoint = None
+    # Page-wide auth defaults (only enforced when an AuthProvider is configured).
+    # Set ``login_required = False`` to make every route on the page public, or
+    # ``required_groups = [...]`` to gate every route — including RCRUD
+    # sub-routes — on group membership. Per-method @public / @require_groups
+    # decorators override these.
+    login_required = True
+    required_groups = None
+
+    def __init__(self, static_folder=None, static_url_path=None, menu=None):
+        self.name = self.name or self.__class__.__name__.capitalize()
+        self.endpoint = self.endpoint or self.__class__.__name__.lower()
+
+        self.static_folder = static_folder
+        self.static_url_path = static_url_path
+        self._urls = []
+        for p in dir(self):
+            attr = getattr(self, p)
+            if hasattr(attr, "_urls"):
+                self._urls = attr._urls
+        menu_val = menu if menu is not None else getattr(self, "menu", None)
+        if menu_val is None:
+            link = self.url.lstrip("/") if self.url else self.endpoint
+            self.menu = {
+                "type": "item",
+                "title": self.name,
+                "icon": self.icon,
+                "link": link,
+            }
+        else:
+            self.menu = menu_val
+
+        self.datasources = {}
+        for name, method_name in self._datasources.items():
+            self.datasources[name] = getattr(self, method_name)
+
+        self.livesources = {}
+        for name, (method_name, interval) in self._livesources.items():
+            self.livesources[name] = (getattr(self, method_name), interval)
+
+    def t(self, msg_id, args=None):
+        return self.construct.t(msg_id, args)
+
+    @property
+    def current_user(self):
+        """The logged-in user as a normalized dict, or None.
+
+        None when no ``AuthProvider`` is configured or nobody is signed in.
+        Portable across auth stacks -- see ``AuthProvider.current_user``. Must
+        be accessed within a request context.
+        """
+        construct = getattr(self, "construct", None)
+        auth = construct.auth if construct is not None else None
+        return auth.current_user() if auth is not None else None
+
+    def get_blueprint(self, construct):
+        """
+        Create Flask blueprint.
+        """
+        # Store construct instance
+        self.construct = construct
+
+        # If the static_url_path is not provided, use the construct's
+        if not self.static_url_path:
+            self.static_url_path = construct.static_url_path
+
+        # Generate URL
+        if not self.url:
+            self.url = f"{construct.url}{self.endpoint}"
+
+        if getattr(construct, "enforce_trailing_slash", False):
+            if self.url and self.url != "/" and not self.url.endswith("/"):
+                self.url = self.url + "/"
+
+        # If we're working from the root of the site, set prefix to None
+        if self.url == "/":
+            self.url = None
+            # prevent construct static files from conflicting with flask static files
+            if not self.static_url_path:
+                self.static_folder = "static"
+                self.static_url_path = "/static/construct"
+
+        # If name is not provided, use class name
+        if self.name is None:
+            self.name = self.__class__.__name__
+
+        # Create blueprint and register rules
+
+        self.blueprint = Blueprint(
+            self.endpoint,
+            __name__,
+            url_prefix=self.url,
+            template_folder="templates",
+            static_folder=self.static_folder,
+            static_url_path=self.static_url_path,
+        )
+
+        for url, name, methods in self._curls:
+            kwargs = {"methods": methods}
+            if getattr(construct, "strict_slashes", None) is not None:
+                kwargs["strict_slashes"] = construct.strict_slashes
+
+            if getattr(construct, "enforce_trailing_slash", False):
+                if url != "/" and url != "" and not url.endswith("/"):
+                    if "." not in url.split("/")[-1]:
+                        url = url + "/"
+
+            self.blueprint.add_url_rule(url, name, getattr(self, name), **kwargs)
+
+        return self.blueprint
+
+    def _run_view(self, f, *args, **kwargs):
+        return f(self, *args, **kwargs)
+
+
+class ComponentPageBase(PageBase):
+    """Base class for component-based pages."""
+
+    layout = None
+
+    def get_blueprint(self, construct):
+        blueprint = super().get_blueprint(construct)
+        self._register_live_endpoints(blueprint, construct)
+        return blueprint
+
+    def _register_live_endpoints(self, blueprint, construct):
+
+        for source_name, (method, interval) in self.livesources.items():
+
+            def make_poll_view(m, sname, page_self):
+                def poll_view():
+                    root = page_self.definition()
+                    comp = page_self._find_live_component(root, sname)
+                    data = m()
+                    if inspect.isgenerator(data):
+                        data = next(data, {})
+                    if comp is not None:
+                        comp._live_data = data
+                        page_self._resolve_livesources(root)
+                        return comp.render()
+                    return "", 204
+
+                poll_view.__name__ = f"live_poll_{sname}"
+                return poll_view
+
+            def make_sse_view(m, sname):
+                def sse_view():
+                    def generate():
+                        result = m()
+                        if inspect.isgenerator(result):
+                            for item in result:
+                                yield f"event: update\ndata: {json.dumps(item)}\n\n"
+                            yield f"event: {SSE_DONE}\ndata: {json.dumps({'status': SSE_DONE})}\n\n"
+                        else:
+                            yield f"event: update\ndata: {json.dumps(result)}\n\n"
+
+                    return Response(
+                        stream_with_context(generate()),
+                        mimetype="text/event-stream",
+                        headers={
+                            "Cache-Control": "no-cache",
+                            "X-Accel-Buffering": "no",
+                        },
+                    )
+
+                sse_view.__name__ = f"live_sse_{sname}"
+                return sse_view
+
+            poll_url = f"/live/{source_name}/poll"
+            sse_url = f"/live/{source_name}/sse"
+            if getattr(construct, "enforce_trailing_slash", False):
+                poll_url += "/"
+                sse_url += "/"
+
+            rule_kwargs = {"methods": ["GET"]}
+            if getattr(construct, "strict_slashes", None) is not None:
+                rule_kwargs["strict_slashes"] = construct.strict_slashes
+
+            blueprint.add_url_rule(
+                poll_url,
+                f"live_poll_{source_name}",
+                make_poll_view(method, source_name, self),
+                **rule_kwargs,
+            )
+            blueprint.add_url_rule(
+                sse_url,
+                f"live_sse_{source_name}",
+                make_sse_view(method, source_name),
+                **rule_kwargs,
+            )
+
+    def _find_live_component(self, root: Component, source_name: str):
+        return self.find_component(
+            root,
+            lambda c: isinstance(c, LiveComponent) and c.live_source == source_name,
+        )
+
+    def _resolve_livesources(self, component: Component):
+
+        if isinstance(component, LiveComponent):
+            if component.sse_url is not None:
+                pass  # URLs already set from explicit sse_url / poll_url params
+            elif component.live_source and component.live_source in self.livesources:
+                method, interval = self.livesources[component.live_source]
+                component._poll_url = url_for(
+                    f"{self.endpoint}.live_poll_{component.live_source}"
+                )
+                component._resolved_interval = interval
+                data = method()
+                is_gen = inspect.isgenerator(data)
+                if is_gen:
+                    data = next(data, {})
+                component._live_data = data
+
+                if inspect.isgeneratorfunction(method) or is_gen:
+                    component._sse_url = url_for(
+                        f"{self.endpoint}.live_sse_{component.live_source}"
+                    )
+                else:
+                    component._sse_url = ""
+
+        for child in component.get_children():
+            self._resolve_livesources(child)
+
+    def _resolve_datasources(self, component: Component):
+
+        if isinstance(component, (ChartComponent, CalendarComponent)):
+            if hasattr(component, "datasource") and component.datasource:
+                if component.datasource in self.datasources:
+                    component.data = self.datasources[component.datasource]()
+
+        for child in component.get_children():
+            self._resolve_datasources(child)
+
+    def build_component_from_structure(self, structure: dict) -> "Component":
+
+        component_type_str = structure.get("type")
+        if not component_type_str:
+            raise ValueError("Component structure must have a 'type'")
+
+        component_class = getattr(components, component_type_str, None)
+        if not component_class:
+            raise ValueError(f"Unknown component type: {component_type_str}")
+
+        kwargs = {}
+        for key, value in structure.items():
+            if key == "type":
+                continue
+
+            if key in ["label", "title", "content"] and isinstance(value, str):
+                kwargs[key] = self.t(value)
+            elif key == "components":
+                kwargs[key] = [self.build_component_from_structure(c) for c in value]
+            elif key == "tabs":
+                kwargs[key] = []
+                for tab in value:
+                    new_tab = tab.copy()
+                    if "label" in new_tab:
+                        new_tab["label"] = self.t(new_tab["label"])
+                    if "component" in new_tab and isinstance(
+                        new_tab["component"], dict
+                    ):
+                        new_tab["component"] = self.build_component_from_structure(
+                            new_tab["component"]
+                        )
+                    kwargs[key].append(new_tab)
+            elif key == "fields" and component_class == FormComponent:
+                for field in value:
+                    if "label" in field:
+                        field["label"] = self.t(field["label"])
+                kwargs[key] = [Field(**f) for f in value]
+            elif key == "actions" and component_class == FormComponent:
+                kwargs[key] = [self.build_component_from_structure(a) for a in value]
+            elif key == "action" and isinstance(value, str) and value.startswith("."):
+                method_name = value.lstrip(".")
+                kwargs[key] = getattr(self, method_name, None)
+            else:
+                kwargs[key] = value
+
+        return component_class(**kwargs)
+
+    def definition(self) -> "Component":
+        if self.layout:
+            return self.build_component_from_structure(self.layout)
+        raise NotImplementedError(
+            "ComponentPage must either define a 'layout' attribute "
+            "or override the 'definition()' method."
+        )
+
+    def _set_active_tabs(self, component: Component):
+
+        if isinstance(component, TabsComponent) and component.id:
+            active_tab = request.args.get(f"{component.id}_tab", default=None, type=int)
+            if active_tab is not None:
+                component.active_tab = active_tab
+
+        for child in component.get_children():
+            self._set_active_tabs(child)
+
+    @expose("/")
+    def index(self):
+        root_component = self.definition()
+        self._resolve_datasources(root_component)
+        self._resolve_livesources(root_component)
+        self._set_active_tabs(root_component)
+        return self.render_component(root_component)
+
+    @expose("/_part/<string:component_id>/<int:part_index>")
+    def get_part(self, component_id: str, part_index: int):
+
+        root_component = self.definition()
+
+        target_container = self.find_component_by_id(root_component, component_id)
+
+        if not target_container:
+            return "Container component not found", 404
+
+        part_component = None
+        if isinstance(target_container, TabsComponent):
+            if 0 <= part_index < len(target_container.tabs):
+                part_component = target_container.tabs[part_index].get("component")
+        elif hasattr(target_container, "components") and isinstance(
+            target_container.components, list
+        ):
+            if 0 <= part_index < len(target_container.components):
+                part_component = target_container.components[part_index]
+
+        if part_component:
+            return part_component.render()
+        else:
+            return "Part not found", 404
+
+    def render_component(self, component: Component):
+        return render_template(
+            f"themes/{self.construct.theme}/components/main.html",
+            component=component,
+            construct=self.construct,
+        )
+
+    def find_component(
+        self, component: Component, condition: Callable[[Component], bool]
+    ) -> Optional[Component]:
+        """
+        Traverses the component tree and returns the first component that satisfies the condition (DFS).
+        """
+        if not isinstance(component, Component):
+            return None
+        if condition(component):
+            return component
+        for child in component.get_children():
+            found = self.find_component(child, condition)
+            if found:
+                return found
+        return None
+
+    def find_component_by_id(
+        self, root_component: Component, component_id: str
+    ) -> Optional[Component]:
+        """
+        Finds a component by its ID.
+        """
+        return self.find_component(
+            root_component, lambda c: hasattr(c, "id") and c.id == component_id
+        )
+
+
+class BaseIndexView(PageBase):
+    endpoint = "construct_index"
+    name = "Index"
+
+    @expose("/")
+    def index(self):
+        return render_template("structure/base.html", construct=self.construct)
+
+
+class ExtensionsPage(ComponentPageBase):
+    endpoint = "construct_extensions"
+    name = "Extensions"
+    icon = "extension"
+
+    def definition(self) -> Component:
+        rows = []
+        for ext in self.construct._extensions:
+            status = ext["status"]
+            if status.startswith("Loaded"):
+                bg_color = "var(--fcu-success)"
+                text_color = "var(--fcu-on-success)"
+            elif status == "Error":
+                bg_color = "var(--fcu-danger)"
+                text_color = "var(--fcu-on-danger)"
+            else:
+                bg_color = "var(--fcu-secondary)"
+                text_color = "var(--fcu-on-secondary)"
+
+            status_badge = Markup(  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+                f'<span style="background-color: {bg_color}; color: {text_color}; '
+                f"padding: 2px 6px; border-radius: var(--fcu-border-radius); font-size: var(--fcu-font-size-sm); "
+                f'font-weight: bold; display: inline-block;">{status}</span>'
+            )
+            details = ext["error"] if ext["error"] else ext["value"]
+            rows.append(
+                [
+                    ext["name"],
+                    ext["package"] or "N/A",
+                    ext["version"] or "N/A",
+                    status_badge,
+                    details,
+                ]
+            )
+
+        return components.VerticalLayout(
+            components=[
+                components.Card(
+                    title="extensions-title",
+                    components=[
+                        components.Table(
+                            headers=[
+                                self.t("extensions-name-col"),
+                                self.t("extensions-package-col"),
+                                self.t("extensions-version-col"),
+                                self.t("extensions-status-col"),
+                                self.t("extensions-desc-col"),
+                            ],
+                            rows=rows,
+                        )
+                    ],
+                )
+            ]
+        )
+
+
+class FlaskConstructUI:
+    app = None
+    index_view_class = BaseIndexView
+
+    def __init__(
+        self,
+        app=None,
+        static_folder=None,
+        url=None,
+        static_url_path=None,
+        title=None,
+        footer=None,
+        index_view_class=None,
+        theme=None,
+        design=None,
+        dark_mode=None,
+        auth=None,
+        search=None,
+        notifications=None,
+        discover_extensions=True,
+        strict_slashes=None,
+        check_trailing_slashes=False,
+        enforce_trailing_slash=False,
+    ):
+        self._pages = []
+        self._menu = []
+        self._blueprint_names = set()
+        self._pages_by_endpoint = {}
+        self._registered_pages = set()
+        self.discover_extensions = discover_extensions
+        self.strict_slashes = strict_slashes
+        self.check_trailing_slashes = check_trailing_slashes
+        self.enforce_trailing_slash = enforce_trailing_slash
+        self._extensions = []
+        # Extra l10n directories registered by companion libraries (see
+        # add_l10n_dir). Searched below the app's own `l10n/` but above the
+        # library defaults. `_owns_l10n` records whether this construct created
+        # `app.l10n` (only then is it safe to rebuild its search path).
+        self._l10n_dirs = []
+        self._owns_l10n = False
+        self._auth = auth
+        self._search = search
+        self._notifications = notifications
+        # The only structural theme is `whitelabel`. When no theme is given we
+        # default to it wearing the `adminlte` design, which reproduces the look
+        # of the former `adminlte3` theme (the previous default) for apps that
+        # never set a theme. An app that *explicitly* selects `whitelabel`
+        # without a design gets the plain whitelabel look — so the design
+        # default only fills in for the no-theme case.
+        if theme is None:
+            theme = "whitelabel"
+            if design is None:
+                design = "adminlte"
+        self.theme = theme
+        # `design` selects a built-in skin layered on top of the structural
+        # theme's stylesheet (e.g. "adminlte" or "sandstone"). It does not
+        # change template resolution — only an extra stylesheet is linked, plus
+        # an optional icon-mode override. `dark_mode` controls the color scheme:
+        # None/"light" (light only, default), "dark" (forced dark) or "auto"
+        # (follow the OS `prefers-color-scheme`).
+        if dark_mode not in (None, "auto", "light", "dark"):
+            raise ValueError(
+                "dark_mode must be one of None, 'auto', 'light', 'dark'; "
+                f"got {dark_mode!r}"
+            )
+        self.design = design
+        self.dark_mode = dark_mode
+        self.static_url_path = static_url_path or "static"
+        if static_folder is None:
+            self.static_folder = path.join(path.dirname(__file__), "static")
+        else:
+            self.static_folder = static_folder
+        if url is not None:
+            self.url = url.rstrip("/") + "/"
+        else:
+            self.url = "/"
+        self.title = title
+        self.footer = footer or "Built with Construct UI"
+        self.templatefolder = path.join(path.dirname(__file__), "templates")
+
+        if index_view_class is not None:
+            self.index_view_class = index_view_class
+
+        if app is not None:
+            self.app = app
+            self.init_app(app)
+
+    def construct_static_path(self, filename):
+        return send_from_directory(self.static_folder, filename)
+
+    def init_app(self, app: Flask):
+        # CSRF is on by default in production and off under TESTING so that
+        # test clients can POST directly. Apps may override either way.
+        app.config.setdefault("CONSTRUCT_CSRF_ENABLED", not app.testing)
+        # Pagination bounds: the default page size used when a view does not
+        # set page_size, and the hard cap any requested/declared size is
+        # silently clamped to (also enforced inside the data layer).
+        app.config.setdefault("CONSTRUCT_DEFAULT_PAGE_SIZE", DEFAULT_PAGE_SIZE)
+        app.config.setdefault("CONSTRUCT_MAX_PAGE_SIZE", MAX_PAGE_SIZE)
+        # Auth is enforced only when an AuthProvider was passed to the
+        # constructor. When enabled, all construct routes require login by
+        # default (fail-closed). CONSTRUCT_LOGIN_ENDPOINT overrides the
+        # provider's login_endpoint.
+        app.config.setdefault("CONSTRUCT_AUTH_ENABLED", self._auth is not None)
+        app.config.setdefault("CONSTRUCT_LOGIN_ENDPOINT", None)
+
+        @app.before_request
+        def set_theme():
+            g.construct_theme = self.theme
+            g.construct = self
+
+        @app.before_request
+        def check_trailing_slashes_once():
+            if self.check_trailing_slashes and not getattr(
+                self, "_checked_trailing_slashes", False
+            ):
+                self._checked_trailing_slashes = True
+                self.check_routes_trailing_slashes(app)
+
+        @app.after_request
+        def add_vary_header(response):
+            if "text/html" in response.content_type:
+                existing = response.headers.get("Vary", "")
+                if "X-Up-Target" not in existing:
+                    response.headers["Vary"] = (existing + ", X-Up-Target").lstrip(", ")
+            return response
+
+        @app.before_request
+        def csrf_protect():
+            # Only guard state-changing requests against construct-owned
+            # endpoints; the host app's own routes are left untouched.
+            if not current_app.config.get("CONSTRUCT_CSRF_ENABLED", True):
+                return
+            if (
+                request.method in CSRF_UNSAFE_METHODS
+                and request.blueprint in self._blueprint_names
+            ):
+                validate_csrf_token()
+
+        @app.before_request
+        def auth_protect():
+            # Fail-closed guard over every construct-owned route. Host app
+            # routes (not in a construct blueprint) are untouched. Dynamically
+            # registered RCRUD sub-routes have no per-method rule, so they fall
+            # through to the safe default (login required) and inherit the
+            # parent page's required_groups.
+            if not current_app.config.get("CONSTRUCT_AUTH_ENABLED", False):
+                return
+            if self._auth is None or request.blueprint not in self._blueprint_names:
+                return
+            page = self._pages_by_endpoint.get(request.blueprint)
+            method = (request.endpoint or "").split(".", 1)[-1]
+            rule = (page._auth_rules.get(method) if page is not None else None) or {}
+
+            # Precedence: per-method rule > class-level > global default.
+            page_public = page is not None and not page.login_required
+            if rule.get("public") or (page_public and "groups" not in rule):
+                return
+            if not self._auth.is_authenticated():
+                return self._auth.on_unauthenticated()
+            groups = rule.get("groups") or (
+                page.required_groups if page is not None else None
+            )
+            if groups and not self._auth.has_groups(groups, rule.get("mode", "any")):
+                return self._auth.on_forbidden()
+
+        @app.template_filter("markdown")
+        def markdown_filter(s):
+            if s is None:
+                return ""
+            from markdown_it import MarkdownIt
+
+            md = MarkdownIt("js-default", {"html": True})
+
+            # MarkdownIt passes raw HTML through, so the converted output must be
+            # sanitized before it is marked safe (stored-XSS boundary).
+            return Markup(
+                sanitize_html(md.render(s))
+            )  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+
+        @app.template_filter("orgmode")
+        def orgmode_filter(s):
+            if s is None:
+                return ""
+            from .orgmode import org_to_html
+
+            return Markup(
+                sanitize_html(org_to_html(s))
+            )  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+
+        def translate(msg_id, args=None):
+            # App-wide translator exposed to templates as `t(...)`. Resolves
+            # app.l10n at call time (it is set up further below, and the app may
+            # swap it); the active language is read per-request from g.language.
+            # Lets the app's own plain render_template views — which have no
+            # `construct` in scope — translate too.
+            return app.l10n.t(msg_id, args)
+
+        @app.context_processor
+        def inject_construct():
+            # Expose `construct` to every template, including plain
+            # render_template views and companion-library pages that don't pass
+            # it explicitly (so they can `{% extends "structure/base.html" %}`
+            # or "structure/public.html"). Templates that pass construct=...
+            # still override this. ``current_user`` is the normalized,
+            # auth-stack-agnostic user dict (None when logged out or no auth),
+            # so templates can do ``{{ current_user.name }}`` without reaching
+            # into a provider's native session.
+            user = self._auth.current_user() if self._auth is not None else None
+            return {"construct": self, "current_user": user}
+
+        app.jinja_env.globals.update(
+            live_container=live_container,
+            live_attributes=live_attributes,
+            csrf_field=csrf_field,
+            csrf_token=generate_csrf_token,
+            t=translate,
+            icon=render_icon,
+            next_url=resolve_next,
+        )
+        # Components render through their own standalone Jinja environment,
+        # so the CSRF helpers, translator and icon renderer must be registered
+        # there too.
+        jinja_env.globals.update(
+            csrf_field=csrf_field,
+            csrf_token=generate_csrf_token,
+            t=translate,
+            icon=render_icon,
+        )
+
+        self.app = app
+        app.add_url_rule(
+            "/construct_static/<path:filename>",
+            "construct_static",
+            self.construct_static_path,
+        )
+        if not hasattr(app, "l10n"):
+            # Only add if not already added by the app.
+            app.l10n = Translator()
+            self._owns_l10n = True
+            self._apply_l10n_paths()
+            app.before_request(set_language_from_browser)
+
+        if self.discover_extensions:
+            self.load_extensions()
+
+        if self.index_view_class:
+            self.index_view = self.index_view_class()
+            self._blueprint_names.add(self.index_view.endpoint)
+            self._pages_by_endpoint[self.index_view.endpoint] = self.index_view
+            self._register_page_blueprint(self.index_view)
+
+        for page in self._pages:
+            self._blueprint_names.add(page.endpoint)
+            self._pages_by_endpoint[page.endpoint] = page
+            self._register_page_blueprint(page)
+
+        if self._search is not None or self._notifications is not None:
+            prefix = self.url.rstrip("/") + "/_construct"
+            if self.enforce_trailing_slash and not prefix.endswith("/"):
+                prefix += "/"
+
+            features_bp = Blueprint("construct_features", __name__, url_prefix=prefix)
+            _self = self
+
+            search_url = "/search"
+            notifications_url = "/notifications"
+            if self.enforce_trailing_slash:
+                search_url += "/"
+                notifications_url += "/"
+
+            route_kwargs = {}
+            if self.strict_slashes is not None:
+                route_kwargs["strict_slashes"] = self.strict_slashes
+
+            if self._search is not None:
+                _search = self._search
+
+                @features_bp.route(search_url, **route_kwargs)
+                def search_results():
+                    q = request.args.get("q", "")
+                    results = _search.search(q)
+                    return render_template(
+                        f"themes/{g.construct_theme}/navbar/search_results.html",
+                        construct=_self,
+                        results=results,
+                        query=q,
+                    )
+
+            if self._notifications is not None:
+
+                @features_bp.route(notifications_url, **route_kwargs)
+                def notifications_fragment():
+                    # Just the #fcu-notifications fragment; Unpoly's up-poll
+                    # reloads it on a timer to keep the count + items fresh.
+                    return render_template(
+                        f"themes/{g.construct_theme}/navbar/notifications.html",
+                        construct=_self,
+                    )
+
+            self.app.register_blueprint(features_bp)
+            self._blueprint_names.add("construct_features")
+
+    def load_extensions(self):
+        """Discover and load companion libraries via entry points in the
+        group 'flask_construct_ui.extensions'.
+        """
+        try:
+            eps = entry_points(group="flask_construct_ui.extensions")
+        except TypeError:
+            # Fallback for older python / importlib_metadata select API compatibility
+            try:
+                eps = entry_points().select(group="flask_construct_ui.extensions")
+            except Exception:
+                eps = []
+
+        for ep in eps:
+            ext_info = {
+                "name": ep.name,
+                "value": ep.value,
+                "package": None,
+                "version": None,
+                "status": "Unknown",
+                "error": None,
+            }
+            try:
+                dist = ep.dist
+                if dist is not None:
+                    ext_info["package"] = dist.name
+                    ext_info["version"] = dist.version
+                plugin = ep.load()
+                if isinstance(plugin, PageBase):
+                    self.add_page(plugin)
+                    ext_info["status"] = "Loaded"
+                elif isinstance(plugin, type) and issubclass(plugin, PageBase):
+                    page_instance = plugin()
+                    self.add_page(page_instance)
+                    ext_info["status"] = "Loaded"
+                elif callable(plugin):
+                    plugin(self)
+                    ext_info["status"] = "Loaded"
+                else:
+                    raise TypeError(
+                        f"Extension must be a PageBase instance, subclass, "
+                        f"or callable, got {type(plugin)}"
+                    )
+            except Exception as e:
+                ext_info["status"] = "Error"
+                ext_info["error"] = str(e)
+                logger.error(f"Failed to load extension {ep.name}: {e}", exc_info=True)
+            self._extensions.append(ext_info)
+
+        if self._extensions:
+            self.add_page(ExtensionsPage(), submenu="Manage", submenu_icon="settings")
+
+    def _register_page_blueprint(self, page):
+        """Register ``page``'s blueprint exactly once.
+
+        Pages are tracked by identity, so a page already registered by
+        ``add_page`` (e.g. an extension loaded during ``load_extensions``) is
+        skipped when the ``init_app`` loop revisits it — but a genuine endpoint
+        collision between two *different* pages still surfaces as Flask's normal
+        duplicate-blueprint error instead of being silently dropped.
+        """
+        if page in self._registered_pages:
+            return
+        self._registered_pages.add(page)
+        self.app.register_blueprint(page.get_blueprint(self))
+
+    def check_routes_trailing_slashes(self, app=None):
+        """Check all registered URL rules in the application for missing trailing slashes.
+
+        Logs a warning for any route in construct blueprints that does not end in a slash,
+        except for static file rules and routes with file extensions.
+
+        Returns:
+            list: A list of tuples containing (rule.rule, rule.endpoint) for non-compliant routes.
+        """
+        app = app or self.app
+        if app is None:
+            return []
+
+        warnings = []
+        for rule in app.url_map.iter_rules():
+            # Skip static routes
+            if "static" in rule.endpoint or rule.endpoint == "static":
+                continue
+
+            parts = rule.endpoint.split(".", 1)
+            bp_name = parts[0] if len(parts) > 1 else rule.endpoint
+            if bp_name not in self._blueprint_names and bp_name != "construct_features":
+                continue
+
+            path = rule.rule
+
+            # Exclude paths ending with common file extensions or having extension-like patterns
+            if path.split("?")[0].split("/")[-1].count(".") > 0:
+                continue
+
+            if not path.endswith("/"):
+                warnings.append((rule.rule, rule.endpoint))
+                app.logger.warning(
+                    f"Construct UI: Route '{rule.rule}' (endpoint '{rule.endpoint}') "
+                    f"does not end with a trailing slash '/'. This may cause 308 redirects."
+                )
+        return warnings
+
+    def add_page(self, page, submenu=None, submenu_icon=None):
+        """Register a page and add it to the navigation menu.
+
+        When ``submenu`` is given, the page's menu entry is nested under a
+        collapsible submenu group with that title instead of being placed at
+        the top level. Pages sharing the same ``submenu`` title are collected
+        into the same group, in the order they are added. ``submenu_icon`` sets
+        the icon for the group the first time it is created (themes that render
+        a submenu icon use it; flat themes show the title as a section header).
+        """
+        self._pages.append(page)
+        self._blueprint_names.add(page.endpoint)
+        self._pages_by_endpoint[page.endpoint] = page
+        if self.app is not None:
+            self._register_page_blueprint(page)
+        if hasattr(page, "menu") and page.menu is not False:
+            if isinstance(page.menu, list):
+                pass
+            else:
+                menu = page.menu
+                menu["link"] = (
+                    self.url
+                    + (
+                        "/"
+                        if self.url[-1:] != "/" and page.menu["link"][:1] != "/"
+                        else ""
+                    )
+                    + page.menu["link"]
+                )
+                if submenu is not None:
+                    self._add_to_submenu(submenu, menu, submenu_icon)
+                else:
+                    self._menu.append(menu)
+
+    def _add_to_submenu(self, title, item, icon="folder"):
+        """Place ``item`` under the submenu group named ``title``.
+
+        Reuses an existing group with the same title if one was already
+        created, otherwise appends a new submenu entry at the current position.
+        """
+        for entry in self._menu:
+            if entry.get("type") == "submenu" and entry.get("title") == title:
+                entry["subitems"].append(item)
+                return
+        self._menu.append(
+            {
+                "type": "submenu",
+                "title": title,
+                "icon": icon,
+                "subitems": [item],
+            }
+        )
+
+    def _apply_l10n_paths(self):
+        """(Re)build the translator's search path.
+
+        Precedence, highest first: the application's own ``l10n/``, then any
+        directories registered by companion libraries (in registration order),
+        then the library defaults. Only meaningful when this construct owns
+        ``app.l10n`` (the host app didn't supply its own).
+        """
+        self.app.l10n.set_languages(["l10n", *self._l10n_dirs, self.l10n_dir])
+
+    def add_l10n_dir(self, path):
+        """Register an extra l10n directory, e.g. one shipped by a companion
+        library.
+
+        Keys there fill in below the application's own ``l10n/`` but override
+        the library defaults, and any language shipped only by ``path`` becomes
+        available. Safe to call before or after ``init_app``: once the app is
+        initialised the search path is rebuilt immediately. It is a no-op when
+        the host app supplied its own ``app.l10n`` (this construct does not own
+        it, so its paths are left untouched).
+        """
+        if path not in self._l10n_dirs:
+            self._l10n_dirs.append(path)
+        if self.app is not None and self._owns_l10n:
+            self._apply_l10n_paths()
+
+    def t(self, msg_id, args=None):
+        return self.app.l10n.t(msg_id, args)
+
+    @property
+    def notices(self):
+        if self._notifications is not None:
+            return self._notifications.get_notices()
+        return []
+
+    @property
+    def notify_count(self):
+        if self._notifications is not None:
+            return self._notifications.count
+        return 0
+
+    @property
+    def auth(self):
+        return self._auth
+
+    @property
+    def navbar_features_available(self):
+        """Whether navbar search/notifications should be rendered.
+
+        Hidden when an auth provider is configured and the current user is not
+        authenticated: every construct route (including the search and
+        notification-poll endpoints) is gated behind auth, so for a logged-out
+        user those controls are dead — the search returns a login redirect and
+        the notifications poll fails. Always available when no auth is set.
+        Must be called within a request context (reads the auth state).
+        """
+        if self._auth is None:
+            return True
+        return self._auth.is_authenticated()
+
+    @property
+    def search(self):
+        return self._search
+
+    @property
+    def notifications(self):
+        return self._notifications
+
+    @property
+    def search_url(self):
+        if self._search is None:
+            return None
+        return self.url.rstrip("/") + "/_construct/search"
+
+    @property
+    def notifications_url(self):
+        """URL of the notifications fragment endpoint (for Unpoly polling)."""
+        if self._notifications is None:
+            return None
+        return self.url.rstrip("/") + "/_construct/notifications"
+
+    @property
+    def menu(self):
+        return self._menu
+
+    @property
+    def titleFromLink(self):
+        for item in self.menu:
+            if item["type"] == "submenu":
+                for subitem in item["subitems"]:
+                    if "link" in subitem and subitem["link"] == self.page:
+                        return subitem["title"]
+
+            if "link" in item and item["link"] == self.page:
+                return item["title"]
+        return ""
+
+    @property
+    def l10n_dir(self):
+        return path.join(path.dirname(__file__), "l10n")
+
+    @property
+    def icon_mode(self):
+        """Active icon-rendering mode ("bootstrap" or "material").
+
+        Resolved from the theme, with any design override applied. Consumed by
+        the ``icon()`` template global (see ``icons.render_icon``).
+        """
+        from .icons import resolve_icon_mode
+
+        return resolve_icon_mode(self.theme, self.design)
+
+    @property
+    def color_scheme(self):
+        """Explicit value for the ``data-fcu-color-scheme`` attribute, or None.
+
+        Returns "light" or "dark" when the scheme is pinned, and None for
+        "auto" so the stylesheet's ``prefers-color-scheme`` media query
+        decides. None (feature off) renders as "light" to keep existing
+        whitelabel apps from following the OS into dark unexpectedly.
+        """
+        if self.dark_mode in (None, "light"):
+            return "light"
+        if self.dark_mode == "dark":
+            return "dark"
+        return None  # "auto"
+
+    @property
+    def design_stylesheet(self):
+        """Static path of the active design stylesheet, or None.
+
+        Designs are shipped per structural theme under
+        ``static/themes/<theme>/designs/<design>.css``. Returns None when no
+        design is selected or the file does not exist on disk.
+        """
+        if not self.design:
+            return None
+        rel = path.join("themes", self.theme, "designs", f"{self.design}.css")
+        if not path.exists(path.join(self.static_folder, rel)):
+            return None
+        return rel.replace(path.sep, "/")
+
+
+def __getattr__(name: str):
+    if name in ("CrudPageBase", "RelatedCrudTab"):
+        from .crud import CrudPageBase, RelatedCrudTab
+
+        if name == "CrudPageBase":
+            return CrudPageBase
+        return RelatedCrudTab
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")