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

flask_construct_ui/navbar.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SearchResult:
+    title: str
+    url: str
+    description: str = ""
+    icon: str = ""
+
+
+@dataclass
+class Notice:
+    title: str
+    message: str = ""
+    url: str = ""
+    icon: str = ""
+    read: bool = False
+
+
+class NavbarFeature:
+    """Common base class for all features that mount on the navbar."""
+
+    pass
+
+
+class GlobalSearch(NavbarFeature):
+    """Subclass and override ``search`` to provide cross-app search.
+
+    The framework registers a ``GET /_construct/search?q=...`` route (relative
+    to the construct URL prefix) and calls ``search(query)`` for each request.
+    Results are rendered using the theme's ``navbar/search_results.html``.
+    """
+
+    def search(self, query: str) -> list[SearchResult]:
+        return []
+
+
+class Notifications(NavbarFeature):
+    """Subclass and override ``get_notices`` to drive the notification bell.
+
+    ``count`` returns the number of unread notices; themes use this for the
+    badge. ``get_notices`` is called once per render — cache inside the method
+    at ``g``-level if the source is expensive.
+    """
+
+    def get_notices(self) -> list[Notice]:
+        return []
+
+    @property
+    def count(self) -> int:
+        return sum(1 for n in self.get_notices() if not n.read)

flask_construct_ui/navigation.py

@@ -0,0 +1,58 @@
+"""Post-save navigation: the ``next`` request parameter.
+
+CRUD success redirects (top-level and RCRUD) resolve their target through
+:func:`resolve_next`, so a link that leads into a form can say where saving,
+deleting or cancelling should land:
+
+  - ``?next=<app-relative path>`` — return there afterwards. The list view's
+    create/edit/delete links pass the current list URL (including filters and
+    pagination) automatically, so form round-trips preserve list state.
+  - ``?next=:record`` — go to the saved record's edit view. Useful for
+    "create, then continue editing". Falls back to the default when no record
+    exists (delete, or a failed create).
+  - no ``next`` — the pre-existing behavior (back to the list view).
+
+Only app-relative paths are honored: anything that does not start with a
+single ``/`` (or contains control characters) is ignored, so a crafted link
+cannot turn the redirect into an open redirect. Page-level policies plug in
+via ``CrudPageBase.get_success_url`` instead of the per-link parameter.
+"""
+
+from flask import request
+
+#: Reserved ``next`` value meaning "the record that was just saved".
+RECORD_TARGET = ":record"
+
+
+def is_safe_next(url):
+    """True when ``url`` is a safe, app-relative redirect target."""
+    if not url or not url.startswith("/"):
+        return False
+    # "//host" and "/\host" are treated as protocol-relative by browsers.
+    if url.startswith("//") or url.startswith("/\\"):
+        return False
+    if any(ord(c) < 0x20 for c in url):
+        return False
+    return True
+
+
+def requested_next():
+    """The raw ``next`` parameter from the query string or form body."""
+    return request.values.get("next")
+
+
+def resolve_next(default, record_url=None):
+    """Resolve the redirect target for a completed form action.
+
+    ``default`` is used when no usable ``next`` was supplied. ``record_url``
+    is the saved record's edit view, substituted for the ``:record``
+    sentinel; pass ``None`` when there is no record to go to.
+    """
+    nxt = requested_next()
+    if not nxt:
+        return default
+    if nxt == RECORD_TARGET:
+        return record_url or default
+    if is_safe_next(nxt):
+        return nxt
+    return default

flask_construct_ui/orgmode.py

@@ -0,0 +1,338 @@
+"""
+Org-mode HTML rendering utility on top of orgparse.
+"""
+
+import re
+import html
+from orgparse import loads
+
+RE_UNORDERED = re.compile(r"^(\s*)([-+*])\s+(.*)$")
+RE_ORDERED = re.compile(r"^(\s*)(\d+)\.\s+(.*)$")
+RE_CHECKBOX = re.compile(r"^\[([ xX-])\]\s*(.*)$")
+
+
+def escape_html(text: str) -> str:
+    return html.escape(text)
+
+
+def parse_inline_formatting(text: str) -> str:
+    """Parse Org-mode inline formatting into HTML."""
+    text = escape_html(text)
+
+    # 1. Links: [[url][label]] or [[url]]
+    text = re.sub(r"\[\[([^\]]+)\]\[([^\]]+)\]\]", r'<a href="\1">\2</a>', text)
+    text = re.sub(r"\[\[([^\]]+)\]\]", r'<a href="\1">\1</a>', text)
+
+    # 2. Code/Verbatim
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])=([^\s=](?:[^=]*?[^\s=])?)=(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<code>\2</code>",
+        text,
+    )
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])~([^\s~](?:[^~]*?[^\s~])?)~(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<code>\2</code>",
+        text,
+    )
+
+    # 3. Bold *text*
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])\*([^\s\*](?:[^\*]*?[^\s\*])?)\*(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<strong>\2</strong>",
+        text,
+    )
+
+    # 4. Italic /text/
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])/([^\s/](?:[^/]*?[^\s/])?)/(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<em>\2</em>",
+        text,
+    )
+
+    # 5. Underline _text_
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])_([^\s_](?:[^_]*?[^\s_])?)_(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<u>\2</u>",
+        text,
+    )
+
+    # 6. Strikethrough +text+
+    text = re.sub(
+        r'(^|[\s(),.:;\'"!?\-\[\]{}<>])\+([^\s\+](?:[^\+]*?[^\s\+])?)\+(?=$|[\s(),.:;\'"!?\-\[\]{}<>])',
+        r"\1<del>\2</del>",
+        text,
+    )
+
+    return text
+
+
+def render_list(list_lines: list[str]) -> str:
+    """Parse list lines into HTML lists (ul/ol) supporting nested elements and checkboxes."""
+    items = []
+    current_item = None
+
+    for line in list_lines:
+        m_ul = RE_UNORDERED.match(line)
+        m_ol = RE_ORDERED.match(line)
+        if m_ul:
+            indent = len(m_ul.group(1))
+            content = m_ul.group(3)
+            current_item = {"indent": indent, "type": "ul", "lines": [content]}
+            items.append(current_item)
+        elif m_ol:
+            indent = len(m_ol.group(1))
+            content = m_ol.group(3)
+            current_item = {"indent": indent, "type": "ol", "lines": [content]}
+            items.append(current_item)
+        else:
+            if current_item is not None and line.strip():
+                current_item["lines"].append(line.strip())
+
+    for item in items:
+        full_content = " ".join(item["lines"])
+        m_chk = RE_CHECKBOX.match(full_content)
+        if m_chk:
+            chk_val = m_chk.group(1)
+            rest = m_chk.group(2)
+            # Use unicode checkboxes (☐/☑) so they render nicely without form input stripping
+            box = "☑" if chk_val.upper() == "X" else "☐"
+            item["html_content"] = (
+                f'<span class="org-checkbox">{box}</span> {parse_inline_formatting(rest)}'
+            )
+        else:
+            item["html_content"] = parse_inline_formatting(full_content)
+
+    if not items:
+        return ""
+
+    html_out = []
+    stack = []
+
+    for item in items:
+        indent = item["indent"]
+        ltype = item["type"]
+
+        while stack and stack[-1][0] > indent:
+            _, last_type = stack.pop()
+            html_out.append(f"</li></{last_type}>")
+
+        if not stack or stack[-1][0] < indent:
+            stack.append((indent, ltype))
+            html_out.append(f"<{ltype}><li>")
+        elif stack[-1][0] == indent:
+            if stack[-1][1] != ltype:
+                _, last_type = stack.pop()
+                html_out.append(f"</li></{last_type}>")
+                stack.append((indent, ltype))
+                html_out.append(f"<{ltype}><li>")
+            else:
+                html_out.append("</li><li>")
+
+        html_out.append(item["html_content"])
+
+    while stack:
+        _, last_type = stack.pop()
+        html_out.append(f"</li></{last_type}>")
+
+    return "".join(html_out)
+
+
+def render_table(table_lines: list[str]) -> str:
+    """Parse table lines into an HTML table."""
+    parsed_rows = []
+    is_separator = lambda s: all(c in "|-+ \t" for c in s)
+    has_header = False
+
+    for line in table_lines:
+        if is_separator(line):
+            if len(parsed_rows) > 0:
+                has_header = True
+            continue
+        cells = [c.strip() for c in line.split("|")[1:-1]]
+        parsed_rows.append(cells)
+
+    if not parsed_rows:
+        return ""
+
+    html_out = ['<table class="org-table">']
+    for idx, row in enumerate(parsed_rows):
+        is_h = has_header and idx == 0
+        html_out.append("<tr>")
+        for cell in row:
+            tag = "th" if is_h else "td"
+            html_out.append(f"<{tag}>{parse_inline_formatting(cell)}</{tag}>")
+        html_out.append("</tr>")
+    html_out.append("</table>")
+    return "\n".join(html_out)
+
+
+def parse_body_to_html(body_text: str) -> str:
+    """Process node body text block-by-block and convert to HTML."""
+    if not body_text.strip():
+        return ""
+
+    lines = body_text.splitlines()
+    blocks = []
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+        stripped = line.strip()
+
+        if not stripped:
+            i += 1
+            continue
+
+        # Code block
+        if stripped.upper().startswith("#+BEGIN_SRC"):
+            parts = stripped.split()
+            lang = parts[1].lower() if len(parts) > 1 else ""
+            src_lines = []
+            i += 1
+            while i < n and not lines[i].strip().upper().startswith("#+END_SRC"):
+                src_lines.append(lines[i])
+                i += 1
+            blocks.append(
+                f'<pre><code class="language-{lang}">'
+                + escape_html("\n".join(src_lines))
+                + "</code></pre>"
+            )
+            i += 1
+            continue
+
+        # Blockquote
+        if stripped.upper().startswith("#+BEGIN_QUOTE"):
+            quote_lines = []
+            i += 1
+            while i < n and not lines[i].strip().upper().startswith("#+END_QUOTE"):
+                quote_lines.append(lines[i])
+                i += 1
+            inner_html = parse_body_to_html("\n".join(quote_lines))
+            blocks.append(f"<blockquote>\n{inner_html}\n</blockquote>")
+            i += 1
+            continue
+
+        # Example
+        if stripped.upper().startswith("#+BEGIN_EXAMPLE"):
+            ex_lines = []
+            i += 1
+            while i < n and not lines[i].strip().upper().startswith("#+END_EXAMPLE"):
+                ex_lines.append(lines[i])
+                i += 1
+            blocks.append(
+                '<pre class="example">' + escape_html("\n".join(ex_lines)) + "</pre>"
+            )
+            i += 1
+            continue
+
+        # Lists
+        m_ul = RE_UNORDERED.match(line)
+        m_ol = RE_ORDERED.match(line)
+        if m_ul or m_ol:
+            list_lines = []
+            while i < n:
+                curr_line = lines[i]
+                curr_stripped = curr_line.strip()
+                if not curr_stripped:
+                    next_idx = i + 1
+                    while next_idx < n and not lines[next_idx].strip():
+                        next_idx += 1
+                    if next_idx < n and (
+                        RE_UNORDERED.match(lines[next_idx])
+                        or RE_ORDERED.match(lines[next_idx])
+                    ):
+                        list_lines.append(curr_line)
+                        i += 1
+                        continue
+                    else:
+                        break
+
+                is_item = RE_UNORDERED.match(curr_line) or RE_ORDERED.match(curr_line)
+                is_indented = curr_line.startswith(" ") or curr_line.startswith("\t")
+                if is_item or is_indented:
+                    list_lines.append(curr_line)
+                    i += 1
+                else:
+                    break
+            blocks.append(render_list(list_lines))
+            continue
+
+        # Tables
+        if stripped.startswith("|"):
+            table_lines = []
+            while i < n and lines[i].strip().startswith("|"):
+                table_lines.append(lines[i].strip())
+                i += 1
+            blocks.append(render_table(table_lines))
+            continue
+
+        # Paragraphs
+        para_lines = []
+        while i < n:
+            curr_line = lines[i]
+            curr_stripped = curr_line.strip()
+            if not curr_stripped:
+                break
+            if (
+                curr_stripped.upper().startswith("#+BEGIN_")
+                or curr_stripped.startswith("|")
+                or RE_UNORDERED.match(curr_line)
+                or RE_ORDERED.match(curr_line)
+            ):
+                break
+            para_lines.append(curr_stripped)
+            i += 1
+
+        para_text = " ".join(para_lines)
+        blocks.append(f"<p>{parse_inline_formatting(para_text)}</p>")
+
+    return "\n".join(blocks)
+
+
+def render_node(node) -> str:
+    """Recursively render a parsed OrgNode tree to HTML."""
+    html_out = []
+
+    if node.level > 0:
+        heading_parts = []
+        if node.todo:
+            heading_parts.append(
+                f'<span class="org-todo org-todo-{node.todo.lower()}">{node.todo}</span>'
+            )
+        if node.priority:
+            heading_parts.append(f'<span class="org-priority">[{node.priority}]</span>')
+
+        raw_heading = node.get_heading(format="raw")
+        heading_parts.append(parse_inline_formatting(raw_heading))
+
+        if node.shallow_tags:
+            tags_html = " ".join(
+                f'<span class="org-tag">{escape_html(t)}</span>'
+                for t in node.shallow_tags
+            )
+            heading_parts.append(f'<span class="org-tags">{tags_html}</span>')
+
+        heading_html = " ".join(heading_parts)
+        level_tag = f"h{min(node.level, 6)}"
+        html_out.append(f"<{level_tag}>{heading_html}</{level_tag}>")
+
+    # Use the raw body — node.body normalises away inline link markup
+    # (`[[url][label]]` collapses to just `label`), which would strip every
+    # link before our own inline parser ever sees it.
+    raw_body = node.get_body(format="raw")
+    if raw_body:
+        html_out.append(parse_body_to_html(raw_body))
+
+    for child in node.children:
+        html_out.append(render_node(child))
+
+    return "\n".join(html_out)
+
+
+def org_to_html(org_text: str) -> str:
+    """Convert Org-mode raw text to HTML using orgparse and custom recursive generation."""
+    if not org_text:
+        return ""
+    root = loads(org_text)
+    return render_node(root)

flask_construct_ui/pagination.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+from flask import current_app, request
+
+# --- Pagination -------------------------------------------------------------
+# Every list-returning query carries an (offset, count) limit. The page size
+# a view declares is clamped to CONSTRUCT_MAX_PAGE_SIZE so neither a
+# misconfigured view nor a crafted request can force an unbounded scan; the
+# data layer applies the same cap as defense in depth (data.effective_limit).
+DEFAULT_PAGE_SIZE = 10
+MAX_PAGE_SIZE = 100
+# Upper bound for the related-field typeahead dropdowns; results narrow as
+# the user types, so they never need a full page-sized result set.
+RELATED_SEARCH_LIMIT = 50
+
+
+def get_pagination(page_size=None):
+    """Return ``(page, per_page, limit)`` for the current request.
+
+    ``page`` comes from the query string, floored at 1 (a negative offset is
+    a server error on some backends). ``per_page`` is the view's ``page_size``
+    (or ``CONSTRUCT_DEFAULT_PAGE_SIZE``) silently clamped to
+    ``CONSTRUCT_MAX_PAGE_SIZE``.
+    """
+    if page_size is None:
+        page_size = current_app.config.get(
+            "CONSTRUCT_DEFAULT_PAGE_SIZE", DEFAULT_PAGE_SIZE
+        )
+    try:
+        page_size = int(page_size)
+    except (TypeError, ValueError):
+        page_size = DEFAULT_PAGE_SIZE
+    max_page_size = current_app.config.get("CONSTRUCT_MAX_PAGE_SIZE", MAX_PAGE_SIZE)
+    try:
+        max_page_size = int(max_page_size)
+    except (TypeError, ValueError):
+        max_page_size = MAX_PAGE_SIZE
+    per_page = min(max(1, page_size), max_page_size)
+    page = max(1, request.args.get("page", 1, type=int))
+    return page, per_page, ((page - 1) * per_page, per_page)

flask_construct_ui/sanitize.py

@@ -0,0 +1,25 @@
+"""
+Central HTML sanitization policy.
+
+Every place the library converts stored/user-supplied content to HTML and
+marks it safe (the ``markdown`` template filter, ``MarkupComponent``,
+calendar cell content) must pass the HTML through :func:`sanitize_html`
+first. Developer-authored template HTML does not go through here.
+"""
+
+import nh3
+
+# nh3's defaults (the ammonia allowlist) strip <script>, event handlers,
+# javascript: URLs and style attributes while keeping formatting tags,
+# lists, tables, links and images — a good match for ProseMirror output.
+ALLOWED_TAGS = nh3.ALLOWED_TAGS | {"img"}
+ALLOWED_ATTRIBUTES = {
+    **nh3.ALLOWED_ATTRIBUTES,
+    "img": {"src", "alt", "title"},
+    "*": {"class"},
+}
+
+
+def sanitize_html(html: str) -> str:
+    """Return ``html`` reduced to the allowlisted tags and attributes."""
+    return nh3.clean(html, tags=ALLOWED_TAGS, attributes=ALLOWED_ATTRIBUTES)