poc

Author: ndonkoHenri

sdk/python/packages/flet-cli/src/flet_cli/commands/publish.py

@@ -6,7 +6,7 @@
 import tempfile
 from pathlib import Path
 
-from flet.controls.types import WebRenderer
+from flet.controls.types import RouteUrlStrategy, WebRenderer
 from flet.utils import copy_tree, is_within_directory, random_string
 from flet_cli.commands.base import BaseCommand
 from flet_cli.utils.project_dependencies import (
@@ -303,7 +303,7 @@ def filter_tar(tarinfo: tarfile.TarInfo):
                 or get_pyproject("tool.flet.web.renderer")
                 or "auto"
             ),
-            route_url_strategy=str(
+            route_url_strategy=RouteUrlStrategy(
                 options.route_url_strategy
                 or get_pyproject("tool.flet.web.route_url_strategy")
                 or "path"

sdk/python/packages/flet-web/src/flet_web/patch_index.py

@@ -6,6 +6,20 @@
 from flet.controls.types import RouteUrlStrategy, WebRenderer
 
 
+def _replace_flet_value(index: str, key: str, value: str) -> str:
+    """
+    Replace a single property inside the `var flet = { ... }` block.
+    """
+    pattern = rf"({re.escape(key)}\s*:\s*)([^,}}]+)"
+    replacement = rf"\1{value}"
+    return re.sub(pattern, replacement, index, flags=re.MULTILINE)
+
+
+def _normalize_base(base_href: str) -> str:
+    base_url = base_href.strip("/").strip() if base_href else ""
+    return "/" if base_url == "" else f"/{base_url}/"
+
+
 def patch_index_html(
     index_path: str,
     base_href: str,
@@ -22,33 +36,44 @@ def patch_index_html(
     with open(index_path, encoding="utf-8") as f:
         index = f.read()
 
+    base = _normalize_base(base_href)
+    if base_href:
+        index = index.replace('<base href="/">', f'<base href="{base}">')
+
     app_config = []
 
     if pyodide and pyodide_script_path:
         module_name = Path(pyodide_script_path).stem
         app_config.append("flet.pyodide = true;")
         app_config.append(f"flet.micropipIncludePre = {str(pyodide_pre).lower()};")
-        app_config.append(f'flet.pythonModuleName = "{module_name}";')
+        app_config.append(f"flet.pythonModuleName = {module_name!r};")
 
-    app_config.append(f"flet.noCdn={str(no_cdn).lower()};")
-    app_config.append(f'flet.webRenderer="{web_renderer.value}";')
-    app_config.append(
-        f'flet.routeUrlStrategy="{route_url_strategy if isinstance(route_url_strategy, str) else route_url_strategy.value}";'
-    )
+    app_config.append(f"flet.noCdn = {str(no_cdn).lower()};")
+    app_config.append(f"flet.webRenderer = {web_renderer.value!r};")
+    app_config.append(f"flet.routeUrlStrategy = {route_url_strategy.value!r};")
 
     if websocket_endpoint_path:
-        app_config.append(f'flet.webSocketEndpoint="{websocket_endpoint_path}";')
+        app_config.append(f"flet.webSocketEndpoint={websocket_endpoint_path!r};")
 
     index = index.replace(
         "<!-- fletAppConfig -->",
         "<script>\n{}\n</script>".format("\n".join(app_config)),
     )
 
-    if base_href:
-        base_url = base_href.strip("/").strip()
-        index = index.replace(
-            '<base href="/">',
-            '<base href="{}">'.format("/" if base_url == "" else f"/{base_url}/"),
+    # Update flet bootstrap object to respect base-url and routing options.
+    index = _replace_flet_value(index, "pyodide", str(pyodide).lower())
+    index = _replace_flet_value(index, "noCdn", str(no_cdn).lower())
+    index = _replace_flet_value(index, "webRenderer", f"{web_renderer.value!r}")
+    index = _replace_flet_value(
+        index, "routeUrlStrategy", f"{route_url_strategy.value!r}"
+    )
+    index = _replace_flet_value(index, "entrypointBaseUrl", f"{base!r}")
+    index = _replace_flet_value(index, "assetBase", f"{base!r}")
+    index = _replace_flet_value(index, "canvasKitBaseUrl", f"'{base}canvaskit/'")
+    index = _replace_flet_value(index, "pyodideUrl", f"'{base}pyodide/pyodide.js'")
+    if websocket_endpoint_path:
+        index = _replace_flet_value(
+            index, "webSocketEndpoint", f"{websocket_endpoint_path!r}"
         )
 
     if app_name:

sdk/python/packages/flet/docs/apps/examples-gallery/requirements.txt

@@ -14,22 +14,22 @@ example_images: ../test-images/examples/material/golden/macos/checkbox
 --8<-- "{{ examples }}/basic.py"
 ```
 
-{{ iframe(route="checkbox/basic", height="400") }}
+{{ demo("checkbox/basic", height="400", width="80%") }}
 
 ### Handling events
 
 ```python
 --8<-- "{{ examples }}/handling_events.py"
 ```
 
-{{ iframe(route="checkbox/handling_events", height="520") }}
+{{ demo("checkbox/handling_events", height="200", width="80%") }}
 
 ### Styled checkboxes
 
 ```python
 --8<-- "{{ examples }}/styled.py"
 ```
 
-{{ iframe(route="checkbox/styled", height="520") }}
+{{ demo("checkbox/styled", height="200", width="80%") }}
 
 {{ class_members(class_name) }}

sdk/python/packages/flet/docs/controls/checkbox.md

@@ -1,4 +1,5 @@
 import os
+from typing import Optional
 from urllib.parse import urlparse
 
 from .cli_to_md import render_flet_cli_as_markdown
@@ -128,13 +129,16 @@ def flet_cli_as_markdown(command: str = "", subcommands_only: bool = True):
             command=command, subcommands_only=subcommands_only
         )
 
+    @env.macro
+    def controls_overview():
+        return render_controls_overview()
+
     @env.macro
     def iframe(
         src=None,
         *,
         route=None,
         base="/apps/examples-gallery/dist/index.html#/",
-        # base="http://127.0.0.1:3000/",
         width="100%",
         height="480",
         title=None,
@@ -153,5 +157,20 @@ def iframe(
         )
 
     @env.macro
-    def controls_overview():
-        return render_controls_overview()
+    def demo(
+        route: str,
+        *,
+        width: str = "100%",
+        height: str = "350",
+        title: Optional[str] = None,
+    ):
+        """
+        Embed an examples gallery route as a centered demo iframe.
+        """
+        return render_iframe(
+            route=route,
+            base="/apps/examples-gallery/dist/index.html#/",
+            width=width,
+            height=height,
+            title=title,
+        )

sdk/python/packages/flet/docs/extras/macros/__init__.py

@@ -3,7 +3,10 @@
 from urllib.parse import urlparse
 
 # Default iframe base can be overridden for local dev via FLET_IFRAME_BASE.
-DEFAULT_IFRAME_BASE = os.environ.get("FLET_IFRAME_BASE", "/apps/dist/index.html#/")
+# Points to the published examples gallery bundled with the docs.
+DEFAULT_IFRAME_BASE = os.environ.get(
+    "FLET_IFRAME_BASE", "/apps/examples-gallery/dist/index.html#/"
+)
 
 
 def _prettify_token(token: str) -> str:
@@ -39,7 +42,7 @@ def render_iframe(
 
     When route is provided, the iframe source is constructed from the base URL.
     The base defaults to the published examples gallery served by MkDocs:
-    /assets/dist/index.html#/ (override with FLET_IFRAME_BASE).
+    /apps/examples-gallery/dist/index.html#/ (override with FLET_IFRAME_BASE).
     """
     base = base or DEFAULT_IFRAME_BASE
 
@@ -56,12 +59,14 @@ def render_iframe(
         raise ValueError("Either src or route must be provided")
 
     if title is None:
-        parsed = urlparse(src)
-        candidate = parsed.path or src
-        if "." not in candidate:
-            title = _pretty_from_route(route or candidate)
+        # Prefer a human-friendly title from the route when available, even if
+        # the underlying src includes an index.html with a fragment.
+        if route:
+            title = _pretty_from_route(route)
         else:
-            title = "iframe"
+            parsed = urlparse(src)
+            candidate = parsed.path or src
+            title = _pretty_from_route(candidate) if "." not in candidate else "iframe"
 
     attrs = [
         f'src="{src}"',
@@ -73,4 +78,6 @@ def render_iframe(
     ]
     if allow:
         attrs.append(f'allow="{allow}"')
-    return f"<iframe {' '.join(attrs)}></iframe>"
+    iframe_html = f"<iframe {' '.join(attrs)}></iframe>"
+
+    return f'<div style="display:flex; justify-content:center;">{iframe_html}</div>'

sdk/python/packages/flet/docs/extras/macros/iframe.py

@@ -96,7 +96,6 @@ watch:
   - ../../../../LICENSE
   - ../../../../README.md
 
-
 # Plugins
 plugins:
   # - footnotes
@@ -163,6 +162,10 @@ plugins:
         - source_dir: integration_tests
           target_url_path: test-images
           include_exts: [".png", ".gif", ".svg"]
+  - examples_gallery:
+      src: apps/examples-gallery/src/main.py
+      dist: apps/examples-gallery/dist
+      base_url: apps/examples-gallery/dist
 
 # Markdown Extensions
 markdown_extensions:

sdk/python/packages/flet/mkdocs.yml

@@ -31,6 +31,9 @@ web = ["flet-web"]
 [project.scripts]
 flet = "flet.cli:main"
 
+[project.entry-points."mkdocs.plugins"]
+examples_gallery = "flet.docs_plugins.examples_gallery:ExamplesGalleryPlugin"
+
 [dependency-groups]
 extensions = [
     "flet-ads",

sdk/python/packages/flet/pyproject.toml

@@ -0,0 +1 @@
+# MkDocs integration helpers (e.g., examples gallery plugin).

sdk/python/packages/flet/src/flet/docs_plugins/__init__.py

@@ -0,0 +1,98 @@
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin
+
+
+def _latest_mtime(root: Path) -> float:
+    """Return the latest modification time for all files under a directory."""
+    mtimes = []
+    for path in root.rglob("*"):
+        if path.is_file():
+            mtimes.append(path.stat().st_mtime)
+    return max(mtimes) if mtimes else 0.0
+
+
+class ExamplesGalleryPlugin(BasePlugin):
+    """Build the examples gallery Flet app before MkDocs runs.
+
+    This plugin:
+    - Finds the examples gallery entry point (default: docs/apps/examples-gallery/src/main.py).
+    - Runs `flet publish` (via `uv run --active`) into the configured dist folder.
+    - Skips the build when the dist/index.html is newer than the source tree.
+
+    Env opts:
+    - FLET_SKIP_EXAMPLES_GALLERY=1 — skip building (useful for fast local docs iteration).
+
+    Config options (mkdocs.yml):
+    - enabled: bool (default True)
+    - src: path to the gallery main.py relative to docs_dir
+    - dist: output folder relative to docs_dir
+    - base_url: base URL passed to `--base-url`
+    - command: optional custom command list to run instead of the default
+    - env: optional extra env vars to inject into the command
+    """
+
+    config_scheme = (
+        ("enabled", config_options.Type(bool, default=True)),
+        ("src", config_options.Type(str, default="apps/examples-gallery/src/main.py")),
+        ("dist", config_options.Type(str, default="apps/examples-gallery/dist")),
+        ("base_url", config_options.Type(str, default="apps/examples-gallery/dist")),
+        ("command", config_options.Type(list, default=None)),
+        ("env", config_options.Type(dict, default=None)),
+    )
+
+    def on_pre_build(self, config: MkDocsConfig) -> None:
+        """
+        Optionally publish the examples gallery before the docs build.
+
+        - Honours `enabled` and `FLET_SKIP_EXAMPLES_GALLERY`.
+        - Skips when the existing dist/index.html is newer than the source tree.
+        - Runs the configured command (or the default `uv run --active flet publish ...`)
+          with `docs_dir` as the working directory and merged env vars.
+        """
+        if not self.config.get("enabled", True):
+            return
+        if os.environ.get("FLET_SKIP_EXAMPLES_GALLERY"):
+            return
+
+        docs_dir = Path(config["docs_dir"])
+        src = docs_dir / self.config["src"]
+        dist_dir = docs_dir / self.config["dist"]
+        dist_index = dist_dir / "index.html"
+
+        if not src.exists():
+            return
+
+        src_mtime = _latest_mtime(src.parent)
+        dist_mtime = dist_index.stat().st_mtime if dist_index.exists() else 0.0
+        if dist_mtime >= src_mtime:
+            return
+
+        cmd: Optional[list[str]] = self.config.get("command")
+        if not cmd:
+            cmd = [
+                "uv",
+                "run",
+                "--active",
+                "flet",
+                "publish",
+                str(src),
+                "--distpath",
+                str(dist_dir),
+                "--base-url",
+                self.config["base_url"],
+                "--route-url-strategy",
+                "hash",
+                "--pre",
+            ]
+
+        env: dict[str, str] = dict(os.environ)
+        extra_env = self.config.get("env") or {}
+        env.update({k: str(v) for k, v in extra_env.items()})
+
+        subprocess.run(cmd, cwd=docs_dir, check=True, env=env)