flask-construct-ui 0.12.0__tar.gz → 0.12.2__tar.gz

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-construct-ui
-Version: 0.12.0
+Version: 0.12.2
 Summary: A UI toolkit for Flask with CRUD and component features.
 Author-email: Olof Tjerngren <olof@tjerngren.net>
 License-Expression: LGPL-3.0-or-later

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/base.py

@@ -1131,6 +1131,7 @@ class FlaskConstructUI(MenuMixin):
         groups=None,
         visible=None,
         weight=None,
+        match=None,
     ):
         """Register a page and add it to the navigation menu.
 
@@ -1152,13 +1153,22 @@ class FlaskConstructUI(MenuMixin):
         ``weight`` orders the entry among its siblings (default 0, ties keep
         registration order), which is what lets a provider place entries around
         statically registered pages.
+
+        ``match`` names other URLs the entry stands for, so it is shown as
+        current there too: a pattern string (``"/user/diary/*"``; ``*`` is
+        anything, ``:name`` one path segment), a list of them, or a callable
+        returning either per request — for an entry that redirects somewhere
+        that depends on who is asking. The paths below the entry's own link
+        always count; see :attr:`menu_current`.
         """
         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)
-        self._add_page_menu_entry(page, submenu, submenu_icon, groups, visible, weight)
+        self._add_page_menu_entry(
+            page, submenu, submenu_icon, groups, visible, weight, match
+        )
 
     def _apply_l10n_paths(self):
         """(Re)build the translator's search path.

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/components/pivot.py

@@ -37,6 +37,11 @@ from .core import Component, _t, jinja_env
 #: Tones a cell or column may carry; each maps to ``fcu-pivot--<tone>``.
 TONES = ("success", "warning", "danger", "info", "muted")
 
+#: What ``unsaved=`` may ask ``core.js`` to do while boxes differ from what
+#: the server rendered: mark the boxes and totals, say so beside Save, warn
+#: before the page or the pivot's fragment is left.
+UNSAVED = ("mark", "status", "warn")
+
 # Separates the name from the keys and the keys from each other. Keys are
 # percent-encoded with nothing kept safe, so neither can contain it.
 _SEP = ":"
@@ -192,7 +197,18 @@ class PivotFormComponent(Component):
       or a :class:`PivotCell` whose ``tone`` / ``css_class`` / ``title`` style
       that total; ``grand_total`` may be a zero-argument callable).
       ``total_extra`` is a slot under the totals heading, ``footer_label``
-      heads the totals row (default: ``total_label``).
+      heads the totals row (default: ``total_label``). The built-in sums
+      follow typing in the browser (``core.js``); an app total changes only
+      when the server renders it again. ``live_totals=False`` keeps every
+      total as rendered.
+    * ``unsaved`` picks how the page shows typing that is not saved yet, any
+      of :data:`UNSAVED` (``()`` shows nothing): ``"mark"`` dashes the
+      changed boxes and the totals they move, ``"status"`` adds a live
+      "Unsaved changes" line beside Save (``unsaved_label``), ``"warn"``
+      asks before leaving the page or replacing the pivot. Whatever is
+      chosen, the form carries ``data-fcu-unsaved`` while anything is
+      unsaved and fires ``fcu:pivot-unsaved`` as that flips, for an app
+      that handles it itself.
     * ``controls`` render inside the form under the table (a row picker,
       extra submit buttons with ``formaction``), after the Save button, which
       stays the form's first submit button so Enter always means save.
@@ -214,6 +230,9 @@ class PivotFormComponent(Component):
     total_label: Optional[str] = None
     total_extra: Any = None
     footer_label: Optional[str] = None
+    live_totals: bool = True
+    unsaved: Any = ()
+    unsaved_label: Optional[str] = None
     controls: List[Any] = field(default_factory=list)
     save: bool = True
     save_label: Optional[str] = None
@@ -223,6 +242,12 @@ class PivotFormComponent(Component):
 
     def __post_init__(self):
         _check_name(self.name, "name")
+        if isinstance(self.unsaved, str):
+            self.unsaved = (self.unsaved,)
+        self.unsaved = tuple(self.unsaved)
+        for mode in self.unsaved:
+            if mode not in UNSAVED:
+                raise ValueError(f"PivotForm unsaved {mode!r} is not one of {UNSAVED}")
         for tone in [c.tone for c in self.columns]:
             if tone is not None and tone not in TONES:
                 raise ValueError(f"PivotColumn tone {tone!r} is not one of {TONES}")
@@ -352,6 +377,13 @@ class PivotFormComponent(Component):
             row_totals=row_totals,
             column_totals=column_totals,
             grand=grand,
+            # Which totals are the built-in sums, which core.js keeps live
+            # while typing; an app total is left as rendered.
+            live={
+                "row": self.live_totals and self.row_total is None,
+                "column": self.live_totals and self.column_total is None,
+                "grand": self.live_totals and self.grand_total is None,
+            },
             input_name=lambda row, column: self.input_name(
                 self.name, row.key, column.key
             ),
@@ -360,6 +392,11 @@ class PivotFormComponent(Component):
                 "total": total_label,
                 "footer": self.footer_label or total_label,
                 "save": self.save_label or _t("pivot-save", default="Save"),
+                "unsaved": self.unsaved_label
+                or _t("pivot-unsaved", default="Unsaved changes"),
+                "leave": _t(
+                    "pivot-unsaved-leave", default="Leave without saving your changes?"
+                ),
             },
         )
 

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/contrast.py

@@ -294,6 +294,40 @@ PAIRS = [
     ("input border on info tint", "--fcu-border-input", "--fcu-alert-info-bg", UI),
     ("pivot row heading", "--fcu-text", "--fcu-pivot-rowhead-bg", TEXT),
     ("pivot row heading link", "--fcu-link", "--fcu-pivot-rowhead-bg", TEXT),
+    # PivotForm unsaved="mark" / "status": a changed box's border and the
+    # "Unsaved changes" line; muted (weekend) columns sit on the alt surface.
+    ("pivot unsaved box border", "--fcu-pivot-unsaved-color", "--fcu-surface", UI),
+    (
+        "pivot unsaved box border on alt surface",
+        "--fcu-pivot-unsaved-color",
+        "--fcu-surface-alt",
+        UI,
+    ),
+    ("pivot unsaved status", "--fcu-pivot-unsaved-text", "--fcu-surface", TEXT),
+    (
+        "pivot unsaved box border on success tint",
+        "--fcu-pivot-unsaved-color",
+        "--fcu-alert-success-bg",
+        UI,
+    ),
+    (
+        "pivot unsaved box border on warning tint",
+        "--fcu-pivot-unsaved-color",
+        "--fcu-alert-warning-bg",
+        UI,
+    ),
+    (
+        "pivot unsaved box border on danger tint",
+        "--fcu-pivot-unsaved-color",
+        "--fcu-alert-danger-bg",
+        UI,
+    ),
+    (
+        "pivot unsaved box border on info tint",
+        "--fcu-pivot-unsaved-color",
+        "--fcu-alert-info-bg",
+        UI,
+    ),
     # Grid: the selection ring is the only indicator of the keyboard cursor,
     # and the error border doubles as the grid's error text colour.
     ("grid selection ring", "--fcu-grid-selected-border", "--fcu-surface", UI),

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/grid.py

@@ -36,6 +36,8 @@ import decimal
 import enum
 from typing import Any
 
+import markupsafe
+
 from . import schema as schema_mod
 from .data import query as data_query
 from .forms import validate_form_data
@@ -365,6 +367,13 @@ def cell_text(field, name, row):
     """The text a cell displays. Always plain text — never markup: a cell
     holds user data, and rendering it as markup would be stored XSS on every
     page that embeds the grid."""
+    if field.has_display_filter():
+        value = field.display_value(name, row, "grid")
+        if isinstance(value, markupsafe.Markup):
+            # A filter's markup is meant for HTML surfaces; a grid cell keeps
+            # only its text.
+            return value.striptags()
+        return "" if value is None else str(value)
     if field.field_type == "bool":
         return "✓" if getattr(row, name, None) else ""
     value = field.format_value(name, row)

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/l10n/en/main.flt

@@ -106,6 +106,8 @@ kanban-add-item = Add
 kanban-add-placeholder = New item…
 
 pivot-save = Save
+pivot-unsaved = Unsaved changes
+pivot-unsaved-leave = Leave without saving your changes?
 pivot-total = Total
 
 period-nav = Period

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/l10n/sv/main.flt

@@ -107,6 +107,8 @@ kanban-add-item = Lägg till
 kanban-add-placeholder = Ny post…
 
 pivot-save = Spara
+pivot-unsaved = Osparade ändringar
+pivot-unsaved-leave = Lämna utan att spara ändringarna?
 pivot-total = Summa
 
 period-nav = Period

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/menu.py

@@ -10,6 +10,9 @@ from __future__ import annotations
 
 import hashlib
 import json
+import re
+from functools import lru_cache
+from urllib.parse import urlparse
 
 from flask import g, has_request_context, request
 
@@ -55,12 +58,63 @@ def _menu_fingerprint(items):
             entry.get("title"),
             entry.get("link"),
             entry.get("icon"),
+            entry.get("match"),
             _menu_fingerprint(entry.get("subitems", [])),
         ]
         for entry in items
     ]
 
 
+# --- Which entry is current -------------------------------------------------
+#
+# An entry matches its own link, everything below it (``link/*``) and any
+# ``match`` patterns the app gave it. Of the entries matching a path, the one
+# with the most specific pattern is current: an exact pattern beats a wildcard,
+# then the longer literal prefix wins, then menu order. construct-core.js
+# implements the same rule (`currentMenuLink`) for Unpoly navigations, which
+# never redraw the sidebar; keep the two in step.
+#
+# Pattern syntax, shared with the client: ``*`` matches anything (slashes
+# included), ``:name`` matches one path segment, everything else is literal.
+# Paths and patterns are compared without trailing slashes.
+
+_PATTERN_TOKEN = re.compile(r"(\*|:[A-Za-z][\w-]*)")
+
+
+def _normalize_path(path):
+    """``path`` without query, fragment or trailing slashes ("/" stays)."""
+    path = urlparse(path).path
+    return path.rstrip("/") or "/"
+
+
+@lru_cache(maxsize=512)
+def _pattern_regex(pattern):
+    parts = []
+    for part in _PATTERN_TOKEN.split(pattern):
+        if part == "*":
+            parts.append(".*")
+        elif part.startswith(":") and len(part) > 1:
+            parts.append("[^/]+")
+        else:
+            parts.append(re.escape(part))
+    return re.compile("^" + "".join(parts) + "$")
+
+
+def _pattern_rank(pattern):
+    """How specific ``pattern`` is: (exact, length of its literal prefix)."""
+    literal = _PATTERN_TOKEN.split(pattern, maxsplit=1)[0]
+    return (len(literal) == len(pattern), len(literal))
+
+
+def _link_entries(items):
+    """Every entry in ``items`` that links somewhere, submenus flattened."""
+    for entry in items:
+        if entry.get("type") == "submenu":
+            yield from _link_entries(entry.get("subitems", []))
+        elif entry.get("link"):
+            yield entry
+
+
 class MenuMixin:
     """Menu state and behaviour of :class:`~.base.FlaskConstructUI`."""
 
@@ -80,7 +134,7 @@ class MenuMixin:
         self._menu_poll = poll
 
     def _add_page_menu_entry(
-        self, page, submenu, submenu_icon, groups, visible, weight
+        self, page, submenu, submenu_icon, groups, visible, weight, match=None
     ):
         """Add ``page``'s menu entry; see :meth:`FlaskConstructUI.add_page`."""
         if not hasattr(page, "menu") or page.menu is False:
@@ -106,6 +160,14 @@ class MenuMixin:
             self._menu_predicates = True
         if weight is not None:
             menu["weight"] = weight
+        if match is not None:
+            menu["match"] = match
+        if callable(menu.get("match")):
+            # Like `visible`: it answers to the request, so the menu it renders
+            # (the patterns are on the links) can change on nothing a stamp
+            # key or the auth stamp describes.
+            self._menu_gated = True
+            self._menu_predicates = True
         if menu.get("groups") or menu.get("visible") is not None:
             self._menu_gated = True
         if submenu is not None:
@@ -144,14 +206,16 @@ class MenuMixin:
         self._menu_providers.append((provider, key))
         return provider
 
-    def menu_provider(self, key=None):
+    def menu_provider(self, provider=None, *, key=None):
         """Decorator form of :meth:`add_menu_provider`.
 
         Usable bare (``@construct.menu_provider``) or called with a key
-        (``@construct.menu_provider(key=lambda: feed.version)``).
+        (``@construct.menu_provider(key=lambda: feed.version)``). The bare
+        form arrives as ``provider``: a key is callable too, so telling the
+        two apart by "is it callable" registered the key as the provider.
         """
-        if callable(key):
-            return self.add_menu_provider(key)
+        if provider is not None:
+            return self.add_menu_provider(provider)
 
         def wrap(fn):
             return self.add_menu_provider(fn, key=key)
@@ -207,9 +271,77 @@ class MenuMixin:
                 self._place_entry(items, dict(entry))
         items = self._visible_entries(items)
         _sort_menu(items)
+        for entry in _link_entries(items):
+            # Resolved once per request, so a callable runs once however often
+            # the patterns are read, and the fingerprint sees its result.
+            entry["match"] = self._extra_patterns(entry)
         g._construct_menu = items
         return items
 
+    def _extra_patterns(self, entry):
+        """``entry``'s own ``match`` patterns, as a list of absolute patterns.
+
+        ``match`` is a string (whitespace-separated patterns), a list of them,
+        or a zero-argument callable returning either, run per request. A
+        pattern not starting with "/" is relative to the construct URL, like a
+        page's link.
+        """
+        match = entry.get("match")
+        if callable(match):
+            match = match()
+        if not match:
+            return []
+        if isinstance(match, str):
+            match = match.split()
+        patterns = []
+        for pattern in match:
+            if not pattern.startswith("/"):
+                pattern = self.url.rstrip("/") + "/" + pattern
+            patterns.append(_normalize_path(pattern))
+        return patterns
+
+    def menu_patterns(self, entry):
+        """Every pattern that makes ``entry`` current: its link, the paths
+        below it, and its ``match`` patterns.
+
+        The link at the root (of the site or of the construct URL) does not
+        claim the paths below it — that would be every page.
+        """
+        link = entry.get("link")
+        if not link:
+            return []
+        base = _normalize_path(link)
+        patterns = [base]
+        if base not in ("/", _normalize_path(self.url)):
+            patterns.append(base + "/*")
+        patterns.extend(self._extra_patterns(entry))
+        return patterns
+
+    def _current_entry(self, items, path):
+        """The entry in ``items`` that ``path`` belongs to, or None."""
+        path = _normalize_path(path)
+        best, best_rank = None, None
+        for entry in _link_entries(items):
+            for pattern in self.menu_patterns(entry):
+                if not _pattern_regex(pattern).match(path):
+                    continue
+                rank = _pattern_rank(pattern)
+                if best_rank is None or rank > best_rank:
+                    best, best_rank = entry, rank
+        return best
+
+    @property
+    def menu_current(self):
+        """The entry of :attr:`menu` the current request belongs to, or None.
+
+        See the matching rule above ``_normalize_path``. Fragment endpoints get
+        None for free (nothing matches ``/_construct/menu``); the client marks
+        a reloaded menu against the browser's location instead.
+        """
+        if not has_request_context():
+            return None
+        return self._current_entry(self.menu, request.path)
+
     def _place_entry(self, items, entry):
         """Insert a provider-supplied ``entry`` into the working menu."""
         entry.setdefault("type", "item")
@@ -330,10 +462,11 @@ class MenuMixin:
 
     @property
     def titleFromLink(self):
-        """Title of the menu entry matching the current route, or "".
+        """Title of the menu entry the current route belongs to, or "".
 
-        Compared against ``request.path`` with trailing slashes normalised, the
-        same way the sidebar decides which link is current. (This used to read
+        Uses the same rule as the sidebar's current link (:attr:`menu_current`),
+        so a record's edit view is named after its list's entry and a page an
+        entry claims through ``match`` after that entry. (This used to read
         a ``self.page`` attribute that has never existed on the extension, so
         it raised on every call — harmless while nothing used it, and the cause
         of an empty ``<title>`` once ``page_title`` started depending on it.)
@@ -347,17 +480,8 @@ class MenuMixin:
         """
         if not has_request_context():
             return ""
-        here = request.path.rstrip("/")
-        for item in self._menu:
-            if item.get("type") == "submenu":
-                for subitem in item.get("subitems", []):
-                    link = subitem.get("link")
-                    if link and link.rstrip("/") == here:
-                        return subitem["title"]
-            link = item.get("link")
-            if link and link.rstrip("/") == here:
-                return item["title"]
-        return ""
+        entry = self._current_entry(self._menu, request.path)
+        return entry["title"] if entry else ""
 
     def _add_menu_stamp(self, response):
         # Same problem as the auth stamp, one level down: the sidebar is

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/rcrud.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from functools import cached_property
 from math import ceil
 from flask import (
+    abort,
     current_app,
     flash,
     g,
@@ -210,6 +211,25 @@ class RelatedCrudTab:
             return verdict
         return rule(page, action, row, parent)
 
+    def can_list(self, construct) -> bool | str:
+        """Whether the tab's list may be shown under the current parent.
+
+        The list is part of the parent's page, so it follows the parent
+        page's own access — its ``can_edit`` or ``can_view`` for the parent —
+        whatever ``capabilities`` says about the children: a reader the
+        parent page turns away must not get the children by asking the tab
+        route directly. A denial returns the parent's ``can_edit`` answer, so
+        its message reaches the 403 page.
+        """
+        parent = self.parent_record()
+        if parent is None:
+            return False
+        page = self._parent_view
+        verdict = _capability(page, "edit", parent)
+        if verdict is True or _capability(page, "view", parent) is True:
+            return True
+        return verdict
+
     def can_add(self, construct) -> bool:
         return self._child_capability("add", construct)
 
@@ -229,7 +249,7 @@ class RelatedCrudTab:
         overriding one of those changes the controls and the routes alike.
         """
         hook = getattr(self, f"can_{action}")
-        if action == "add":
+        if action in ("add", "list"):
             return hook(construct) is True
         return hook(row, construct) is True
 
@@ -373,6 +393,11 @@ class RelatedCrudTab:
             return ds, rec
 
         def list_view(id):
+            if rct.parent_record() is None:
+                abort(404)
+            allowed = rct.can_list(construct)
+            if allowed is not True:
+                return forbidden(parent_view, allowed)
             ds = child_dataclass()
             page, per_page, limit = get_pagination(
                 getattr(rct.child_crud_class, "page_size", None)

{flask_construct_ui-0.12.0 → flask_construct_ui-0.12.2}/flask_construct_ui/schema.py

@@ -3,6 +3,27 @@ import datetime
 from .validation import ValidationError, parse_rule
 
 
+class DisplayContext:
+    """What a display filter gets alongside the value it is formatting.
+
+    One object rather than more positional arguments, so later additions
+    don't break filters apps have already written.
+
+    ``surface`` says where the value is being shown: ``"list"`` (the CRUD
+    list), ``"related"`` (a related-records tab), ``"view"`` (a read-only
+    field on the view or edit page), ``"inline"`` (a row of a list field) or
+    ``"grid"`` (a data grid cell, which is plain text only).
+    """
+
+    __slots__ = ("row", "name", "field", "surface")
+
+    def __init__(self, row, name, field, surface):
+        self.row = row
+        self.name = name
+        self.field = field
+        self.surface = surface
+
+
 class SchemaField:
     def __init__(self, field_type, name, **kwargs):
         self.field_type = field_type
@@ -26,6 +47,8 @@ class SchemaField:
         # only replaces the generic "Enter <field>" hint and vanishes on input.
         self.placeholder = kwargs.get("placeholder", None)
         self.help = kwargs.get("help", None)
+        # Display-only filter, ``fn(value, ctx)`` — see ``display_value``.
+        self.display = kwargs.get("display", None)
         self.kwargs = kwargs
         matches = kwargs.get("matches", None)
         self._matches_fn = None
@@ -61,8 +84,52 @@ class SchemaField:
         return 'required aria-required="true"' if self.required else ""
 
     def format_value(self, field, row):
+        """The stored value, as a form control or editor is filled with it.
+
+        This feeds ``value="…"`` attributes as well as read-only text, so it
+        must never return markup. To change only how a value *reads*, use a
+        display filter — see ``display_value``.
+        """
         return getattr(row, field)
 
+    def _display_filter(self):
+        if self.display is not None:
+            return self.display
+        from flask import has_app_context, current_app
+
+        if has_app_context():
+            filters = current_app.config.get("CONSTRUCT_DISPLAY_FILTERS") or {}
+            return filters.get(self.field_type)
+        return None
+
+    def has_display_filter(self):
+        """Whether ``display_value`` differs from ``format_value`` here.
+
+        Templates check this before their built-in per-type rendering (check
+        icons, badges, …), so a filter can restyle any field type, while
+        fields without one render exactly as before.
+        """
+        if type(self).display_value is not SchemaField.display_value:
+            return True
+        return self._display_filter() is not None
+
+    def display_value(self, field, row, surface="list"):
+        """The value as it is shown — never typed — in lists, related tabs,
+        read-only views and grid cells.
+
+        Resolved, most specific first: the field's ``display=`` callable, the
+        app's ``CONSTRUCT_DISPLAY_FILTERS[field_type]``, then ``format_value``
+        unchanged. A filter is called as ``fn(value, ctx)`` with the
+        ``format_value`` result and a :class:`DisplayContext`. It may return
+        ``markupsafe.Markup`` for intentional HTML; anything else is escaped.
+        Subclasses may override this for full control.
+        """
+        value = self.format_value(field, row)
+        fn = self._display_filter()
+        if fn is None:
+            return value
+        return fn(value, DisplayContext(row, field, self, surface))
+
     def parse_value(self, value):
         return value