Merge remote-tracking branch 'upstream/main' into export-event

# Conflicts:
#	reflex/utils/export.py
#	reflex/utils/telemetry.py
#	tests/units/test_telemetry.py

Author: FarhanAliRaza

README.md

@@ -105,153 +105,16 @@ If the `reflex` command is not on your PATH, run it through uv instead: `uv run
 
 ## 🫧 Example App
 
-Let's go over an example: creating an image generation UI around [DALL·E](https://platform.openai.com/docs/guides/images/image-generation?context=node). For simplicity, we just call the [OpenAI API](https://platform.openai.com/docs/api-reference/authentication), but you could replace this with an ML model run locally.
-
- 
+Build an image generation app in Python with Reflex: define the UI, manage state in a class, and call an image model from an event handler.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/reflex-dev/reflex/main/docs/images/dalle.gif" alt="A frontend wrapper for DALL·E, shown in the process of generating an image." width="550" />
+<video src="https://github.com/user-attachments/assets/aaff28ad-8b3c-43bf-967e-439ee34c8a87" width="900" controls muted poster="https://raw.githubusercontent.com/reflex-dev/reflex/main/docs/images/reflex-image-generation-app.png">
+  <a href="https://github.com/user-attachments/assets/aaff28ad-8b3c-43bf-967e-439ee34c8a87">
+    <img src="https://raw.githubusercontent.com/reflex-dev/reflex/main/docs/images/reflex-image-generation-app.png" alt="Preview of an image generation app built with Reflex" width="900">
+  </a>
+</video>
 </div>
 
-&nbsp;
-
-Here is the complete code to create this. This is all done in one Python file!
-
-```python
-import reflex as rx
-import openai
-
-openai_client = openai.OpenAI()
-
-
-class State(rx.State):
-    """The app state."""
-
-    prompt = ""
-    image_url = ""
-    processing = False
-    complete = False
-
-    def get_image(self):
-        """Get the image from the prompt."""
-        if self.prompt == "":
-            return rx.window_alert("Prompt Empty")
-
-        self.processing, self.complete = True, False
-        yield
-        response = openai_client.images.generate(
-            prompt=self.prompt, n=1, size="1024x1024"
-        )
-        self.image_url = response.data[0].url
-        self.processing, self.complete = False, True
-
-
-def index():
-    return rx.center(
-        rx.vstack(
-            rx.heading("DALL-E", font_size="1.5em"),
-            rx.input(
-                placeholder="Enter a prompt..",
-                on_blur=State.set_prompt,
-                width="25em",
-            ),
-            rx.button(
-                "Generate Image",
-                on_click=State.get_image,
-                width="25em",
-                loading=State.processing,
-            ),
-            rx.cond(
-                State.complete,
-                rx.image(src=State.image_url, width="20em"),
-            ),
-            align="center",
-        ),
-        width="100%",
-        height="100vh",
-    )
-
-
-# Add state and page to the app.
-app = rx.App()
-app.add_page(index, title="Reflex:DALL-E")
-```
-
-## Let's break this down.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/reflex-dev/reflex/main/docs/images/dalle_colored_code_example.png" alt="Explaining the differences between backend and frontend parts of the DALL-E app." width="900" />
-</div>
-
-### **Reflex UI**
-
-Let's start with the UI.
-
-```python
-def index():
-    return rx.center(...)
-```
-
-This `index` function defines the frontend of the app.
-
-We use different components such as `center`, `vstack`, `input`, and `button` to build the frontend. Components can be nested within each other
-to create complex layouts. And you can use keyword args to style them with the full power of CSS.
-
-Reflex comes with [60+ built-in components](https://reflex.dev/docs/library) to help you get started. We are actively adding more components, and it's easy to [create your own components](https://reflex.dev/docs/wrapping-react/overview/).
-
-### **State**
-
-Reflex represents your UI as a function of your state.
-
-```python
-class State(rx.State):
-    """The app state."""
-
-    prompt = ""
-    image_url = ""
-    processing = False
-    complete = False
-```
-
-The state defines all the variables (called vars) in an app that can change and the functions that change them.
-
-Here the state is comprised of a `prompt` and `image_url`. There are also the booleans `processing` and `complete` to indicate when to disable the button (during image generation) and when to show the resulting image.
-
-### **Event Handlers**
-
-```python
-def get_image(self):
-    """Get the image from the prompt."""
-    if self.prompt == "":
-        return rx.window_alert("Prompt Empty")
-
-    self.processing, self.complete = True, False
-    yield
-    response = openai_client.images.generate(prompt=self.prompt, n=1, size="1024x1024")
-    self.image_url = response.data[0].url
-    self.processing, self.complete = False, True
-```
-
-Within the state, we define functions called event handlers that change the state vars. Event handlers are the way that we can modify the state in Reflex. They can be called in response to user actions, such as clicking a button or typing in a text box. These actions are called events.
-
-Our DALL·E app has an event handler, `get_image` which gets this image from the OpenAI API. Using `yield` in the middle of an event handler will cause the UI to update. Otherwise the UI will update at the end of the event handler.
-
-### **Routing**
-
-Finally, we define our app.
-
-```python
-app = rx.App()
-```
-
-We add a page from the root of the app to the index component. We also add a title that will show up in the page preview/browser tab.
-
-```python
-app.add_page(index, title="DALL-E")
-```
-
-You can create a multi-page app by adding more pages.
-
 ## 📑 Resources
 
 <div align="center">

docs/advanced_onboarding/code_structure.md

@@ -228,6 +228,10 @@ import reflex as rx
 class State(rx.State):
     v: str = "foo"
 
+    @rx.event
+    def set_v(self, value: str):
+        self.v = value
+
 
 @lru_cache
 def foo():

docs/app/assets/tailwind-theme.css

@@ -1,3 +1,4 @@
+@import 'tailwindcss-scroll-mask';
 @import "tailwindcss-animated";
 
 @custom-variant dark (&:where(.dark, .dark *));

docs/app/reflex_docs/docgen_pipeline.py

@@ -1,5 +1,6 @@
 """Pipeline for rendering reflex-shipped docs via reflex_docgen.markdown."""
 
+import json
 import sys
 import types
 from pathlib import Path
@@ -769,20 +770,95 @@ def _parse_doc(filepath: str | Path) -> Document:
     return parse_document(source)
 
 
+FAQS_START_MARKER = "<!-- faqs-start -->"
+FAQS_END_MARKER = "<!-- faqs-end -->"
+
+
+def _extract_faqs_jsonld(source: str) -> tuple[str, rx.Component | None]:
+    """Strip an FAQ section from the source and return a JSON-LD script for it.
+
+    Looks for content between :data:`FAQS_START_MARKER` and :data:`FAQS_END_MARKER`.
+    Inside that block, each H3 (``### Question``) heading is treated as a question
+    and the following text blocks (until the next H3) make up the answer. The
+    pairs are emitted as a single ``<script type="application/ld+json">`` element
+    using the schema.org ``FAQPage`` shape.
+
+    Returns ``(stripped_source, jsonld_script_or_none)``. The script is ``None``
+    if either marker is missing or no question/answer pairs were found.
+    """
+    if FAQS_START_MARKER not in source or FAQS_END_MARKER not in source:
+        return source, None
+    before, _, rest = source.partition(FAQS_START_MARKER)
+    faq_chunk, _, after = rest.partition(FAQS_END_MARKER)
+    stripped = before + after
+
+    doc = parse_document(faq_chunk)
+    faqs: list[tuple[str, str]] = []
+    current_q: str | None = None
+    current_a_parts: list[str] = []
+
+    def flush() -> None:
+        if current_q is not None:
+            answer = " ".join(p.strip() for p in current_a_parts if p.strip())
+            if answer:
+                faqs.append((current_q, answer))
+
+    for block in doc.blocks:
+        if isinstance(block, HeadingBlock) and block.level == 3:
+            flush()
+            current_q = _spans_to_plaintext(block.children)
+            current_a_parts = []
+        elif current_q is not None and isinstance(block, TextBlock):
+            current_a_parts.append(_spans_to_plaintext(block.children))
+    flush()
+
+    if not faqs:
+        return stripped, None
+
+    schema = {
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        "mainEntity": [
+            {
+                "@type": "Question",
+                "name": q,
+                "acceptedAnswer": {"@type": "Answer", "text": a},
+            }
+            for q, a in faqs
+        ],
+    }
+    jsonld = json.dumps(schema, ensure_ascii=False)
+    return stripped, rx.el.script(jsonld, type="application/ld+json")
+
+
 def render_docgen_document(
     virtual_filepath: str | Path, actual_filepath: str | Path
-) -> rx.Component:
-    """Parse and render a doc file from the reflex package using reflex_docgen."""
-    doc = _parse_doc(actual_filepath)
+) -> tuple[rx.Component, rx.Component | None]:
+    """Render a doc file as ``(body, faq_jsonld)``.
+
+    The FAQ section (between :data:`FAQS_START_MARKER` and
+    :data:`FAQS_END_MARKER`, if present) is stripped from the visible body and
+    returned as a JSON-LD ``<script>`` component for SEO. ``faq_jsonld`` is
+    ``None`` if no FAQ block is found.
+    """
+    source = Path(actual_filepath).read_text(encoding="utf-8")
+    source, faq_script = _extract_faqs_jsonld(source)
     transformer = ReflexDocTransformer(
         virtual_filepath=str(virtual_filepath), filename=str(actual_filepath)
     )
-    return transformer.transform(doc)
+    return transformer.transform(parse_document(source)), faq_script
 
 
 def get_docgen_toc(filepath: str | Path) -> list[tuple[int, str]]:
-    """Extract TOC headings as (level, text) tuples — same format as reflex_docgen's get_toc."""
-    doc = _parse_doc(filepath)
+    """Extract TOC headings as (level, text) tuples.
+
+    The FAQ block (between :data:`FAQS_START_MARKER` and
+    :data:`FAQS_END_MARKER`) is stripped before extraction so its headings do
+    not appear in the TOC — they live only in the emitted JSON-LD.
+    """
+    source = Path(filepath).read_text(encoding="utf-8")
+    source, _ = _extract_faqs_jsonld(source)
+    doc = parse_document(source)
     return [(h.level, _spans_to_plaintext(h.children)) for h in doc.headings]
 
 
@@ -791,3 +867,21 @@ def render_markdown(text: str) -> rx.Component:
     doc = parse_document(text)
     transformer = ReflexDocTransformer()
     return transformer.transform(doc)
+
+
+def render_inline_markdown(text: str, class_name: str = "") -> rx.Component:
+    """Render a short markdown string inline (links, code spans, emphasis).
+
+    Intended for places like prop-table descriptions where the source contains
+    inline markdown (e.g. ``[Foo](/path)``, `` `code` ``) but the surrounding
+    layout expects a single styled text node, not a stack of block-level
+    elements. Block-level markdown (headings, lists, code fences) falls back
+    to the full transformer.
+    """
+    if not text:
+        return rx.fragment()
+    doc = parse_document(text)
+    if len(doc.blocks) == 1 and isinstance(doc.blocks[0], TextBlock):
+        children = _render_spans(doc.blocks[0].children)
+        return rx.text(*children, class_name=class_name)
+    return ReflexDocTransformer().transform(doc)

docs/app/reflex_docs/pages/docs/__init__.py

@@ -212,6 +212,10 @@ def handle_library_doc(
     """Handle docs/library/** docs — component API reference via multi_docs."""
     clist = [title, *get_components_from_frontmatter(actual_path)]
     previews = get_previews_from_frontmatter(actual_path)
+    ll_actual_path = actual_path.replace(".md", "-ll.md")
+    ll_clist: list | None = None
+    if os.path.exists(ll_actual_path):
+        ll_clist = [title, *get_components_from_frontmatter(ll_actual_path)]
     if doc.startswith("docs/library/graphing"):
         graphing_components[resolved.category].append(clist)
     else:
@@ -223,6 +227,7 @@ def handle_library_doc(
         previews=previews,
         component_list=clist,
         title=resolved.display_title,
+        ll_component_list=ll_clist,
     )
 
 
@@ -238,10 +243,12 @@ def get_component_docgen(virtual_doc: str, actual_path: str, title: str):
     def comp(_actual=actual_path, _virtual=virtual_doc):
         toc = get_docgen_toc(_actual)
         doc_content = Path(_actual).read_text(encoding="utf-8")
-        rendered = render_docgen_document(
+        body, faq_script = render_docgen_document(
             virtual_filepath=_virtual, actual_filepath=_actual
         )
-        return ((toc, doc_content), rendered)
+        if faq_script is not None:
+            body = rx.fragment(body, faq_script)
+        return ((toc, doc_content), body)
 
     return make_docpage(resolved.route, resolved.display_title, virtual_doc, comp)