reflex-react-joyride 0.1.0__py3-none-any.whl

reflex_react_joyride/__init__.py

@@ -0,0 +1,81 @@
+"""reflex-react-joyride: guided product tours for Reflex, powered by react-joyride."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+from . import actions
+from .actions import (
+    close,
+    get_state,
+    go_to,
+    next_step,
+    open_tooltip,
+    prev_step,
+    replay,
+    reset,
+    skip,
+    start,
+    stop,
+)
+from .constants import (
+    ACTIONS,
+    EVENTS,
+    FINISHED_STATUSES,
+    JOYRIDE_VERSION,
+    LIFECYCLE,
+    ORIGIN,
+    PLACEMENTS,
+    PORTAL_ELEMENT_ID,
+    STATUS,
+)
+from .events import JoyrideEvent, TourState
+from .joyride import Joyride, joyride
+from .props import (
+    FloatingOptions,
+    Locale,
+    SpotlightPadding,
+    Step,
+    TourOptions,
+    TourStyles,
+)
+
+# pyproject.toml is the single source of truth for the version; read it back
+# from the installed metadata so the two can never drift.
+try:
+    __version__ = _package_version("reflex-react-joyride")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "ACTIONS",
+    "EVENTS",
+    "FINISHED_STATUSES",
+    "JOYRIDE_VERSION",
+    "LIFECYCLE",
+    "ORIGIN",
+    "PLACEMENTS",
+    "PORTAL_ELEMENT_ID",
+    "STATUS",
+    "FloatingOptions",
+    "Joyride",
+    "JoyrideEvent",
+    "Locale",
+    "SpotlightPadding",
+    "Step",
+    "TourOptions",
+    "TourState",
+    "TourStyles",
+    "actions",
+    "close",
+    "get_state",
+    "go_to",
+    "joyride",
+    "next_step",
+    "open_tooltip",
+    "prev_step",
+    "replay",
+    "reset",
+    "skip",
+    "start",
+    "stop",
+]

reflex_react_joyride/actions.py

@@ -0,0 +1,104 @@
+"""Drive a running tour from Python.
+
+Every ``joyride(...)`` created with a ``tour_id`` registers react-joyride's
+``controls`` object in the browser under ``window.__reflexJoyride[tour_id]``.
+The helpers below return ``rx.call_script`` events, so they can be used as
+triggers directly or returned from an event handler::
+
+    rx.button("Start the tour", on_click=rjr.start("main"))
+    rx.button("Next", on_click=rjr.next_step("main"))
+
+They work whether the tour runs uncontrolled or in controlled mode, and they are
+no-ops (with a console warning) if no tour with that id is mounted.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import reflex as rx
+from reflex.event import EventSpec
+
+
+def _call(tour_id: str, method: str, *args: Any, callback: Any = None) -> EventSpec:
+    """Call a method of the controls object registered under ``tour_id``."""
+    js_args = ", ".join(json.dumps(arg) for arg in args)
+    script = (
+        f"(() => {{ const api = window.__reflexJoyride?.[{json.dumps(tour_id)}];"
+        f" if (!api) {{ console.warn('reflex-react-joyride: no tour with id', {json.dumps(tour_id)}); return null; }}"
+        f" return api.{method}({js_args}); }})()"
+    )
+    if callback is not None:
+        return rx.call_script(script, callback=callback)
+    return rx.call_script(script)
+
+
+def start(tour_id: str, index: int | None = None) -> EventSpec:
+    """Start (or restart) the tour, optionally at a given step index."""
+    return _call(tour_id, "start") if index is None else _call(tour_id, "start", index)
+
+
+def stop(tour_id: str, advance: bool = False) -> EventSpec:
+    """Stop the tour. With ``advance=True`` it moves to the next step first."""
+    return _call(tour_id, "stop", advance)
+
+
+def next_step(tour_id: str) -> EventSpec:
+    """Advance to the next step."""
+    return _call(tour_id, "next")
+
+
+def prev_step(tour_id: str) -> EventSpec:
+    """Go back to the previous step."""
+    return _call(tour_id, "prev")
+
+
+def go_to(tour_id: str, index: int) -> EventSpec:
+    """Jump to a specific step index (zero-based)."""
+    return _call(tour_id, "go", index)
+
+
+def close(tour_id: str) -> EventSpec:
+    """Close the current step, advancing to the next one."""
+    return _call(tour_id, "close")
+
+
+def skip(tour_id: str) -> EventSpec:
+    """End the tour, marking it as skipped."""
+    return _call(tour_id, "skip")
+
+
+def reset(tour_id: str, restart: bool = False) -> EventSpec:
+    """Reset the tour to the first step; ``restart=True`` also starts it again."""
+    return _call(tour_id, "reset", restart)
+
+
+def replay(tour_id: str) -> EventSpec:
+    """Replay the current step, re-running its hooks and events."""
+    return _call(tour_id, "replay")
+
+
+def open_tooltip(tour_id: str) -> EventSpec:
+    """Open the tooltip of the current step (skipping its beacon)."""
+    return _call(tour_id, "open")
+
+
+def get_state(tour_id: str, callback: Any) -> EventSpec:
+    """Send the current tour state to ``callback``, an event handler taking a dict."""
+    return _call(tour_id, "info", callback=callback)
+
+
+__all__ = [
+    "close",
+    "get_state",
+    "go_to",
+    "next_step",
+    "open_tooltip",
+    "prev_step",
+    "replay",
+    "reset",
+    "skip",
+    "start",
+    "stop",
+]

reflex_react_joyride/constants.py

@@ -0,0 +1,188 @@
+"""Constants mirroring the literals exported by react-joyride v3.
+
+The values are the exact strings react-joyride emits, so they can be compared
+directly against the payload received by ``on_event`` and friends::
+
+    from reflex_react_joyride import EVENTS, STATUS
+
+    @rx.event
+    def tour_event(self, event: dict):
+        if event["type"] == EVENTS.TOUR_END:
+            self.finished = event["status"] == STATUS.FINISHED
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+#: npm version of react-joyride this component wraps.
+JOYRIDE_VERSION: Final = "3.2.0"
+
+#: The id of the portal element react-joyride renders into.
+PORTAL_ELEMENT_ID: Final = "react-joyride-portal"
+
+
+class ACTIONS:
+    """The action that triggered a state update (``event["action"]``)."""
+
+    INIT: Final = "init"
+    START: Final = "start"
+    STOP: Final = "stop"
+    RESET: Final = "reset"
+    PREV: Final = "prev"
+    NEXT: Final = "next"
+    GO: Final = "go"
+    CLOSE: Final = "close"
+    SKIP: Final = "skip"
+    REPLAY: Final = "replay"
+    UPDATE: Final = "update"
+    COMPLETE: Final = "complete"
+
+
+class EVENTS:
+    """The type of the event (``event["type"]``)."""
+
+    TOUR_START: Final = "tour:start"
+    STEP_BEFORE_HOOK: Final = "step:before_hook"
+    STEP_BEFORE: Final = "step:before"
+    SCROLL_START: Final = "scroll:start"
+    SCROLL_END: Final = "scroll:end"
+    BEACON: Final = "beacon"
+    TOOLTIP: Final = "tooltip"
+    STEP_AFTER: Final = "step:after"
+    STEP_AFTER_HOOK: Final = "step:after_hook"
+    TOUR_END: Final = "tour:end"
+    TOUR_STATUS: Final = "tour:status"
+    TARGET_NOT_FOUND: Final = "error:target_not_found"
+    ERROR: Final = "error"
+
+
+class LIFECYCLE:
+    """The rendering phase of the current step (``event["lifecycle"]``)."""
+
+    INIT: Final = "init"
+    READY: Final = "ready"
+    BEACON_BEFORE: Final = "beacon_before"
+    BEACON: Final = "beacon"
+    TOOLTIP_BEFORE: Final = "tooltip_before"
+    TOOLTIP: Final = "tooltip"
+    COMPLETE: Final = "complete"
+
+
+class ORIGIN:
+    """The UI element that triggered the action (``event["origin"]``)."""
+
+    BUTTON_BACK: Final = "button_back"
+    BUTTON_CLOSE: Final = "button_close"
+    BUTTON_PRIMARY: Final = "button_primary"
+    BUTTON_SKIP: Final = "button_skip"
+    KEYBOARD: Final = "keyboard"
+    OVERLAY: Final = "overlay"
+
+
+class STATUS:
+    """The tour's current status (``event["status"]``)."""
+
+    IDLE: Final = "idle"
+    READY: Final = "ready"
+    WAITING: Final = "waiting"
+    RUNNING: Final = "running"
+    PAUSED: Final = "paused"
+    SKIPPED: Final = "skipped"
+    FINISHED: Final = "finished"
+
+
+#: Statuses that mean the tour is over, one way or another.
+FINISHED_STATUSES: Final = (STATUS.FINISHED, STATUS.SKIPPED)
+
+ActionType = Literal[
+    "init", "start", "stop", "reset", "prev", "next", "go", "close", "skip", "replay", "update", "complete"
+]
+EventType = Literal[
+    "tour:start",
+    "step:before_hook",
+    "step:before",
+    "scroll:start",
+    "scroll:end",
+    "beacon",
+    "tooltip",
+    "step:after",
+    "step:after_hook",
+    "tour:end",
+    "tour:status",
+    "error:target_not_found",
+    "error",
+]
+LifecycleType = Literal["init", "ready", "beacon_before", "beacon", "tooltip_before", "tooltip", "complete"]
+OriginType = Literal["button_back", "button_close", "button_primary", "button_skip", "keyboard", "overlay"]
+StatusType = Literal["idle", "ready", "waiting", "running", "paused", "skipped", "finished"]
+
+#: Placements accepted by the beacon and the tooltip.
+Placement = Literal[
+    "top",
+    "top-start",
+    "top-end",
+    "bottom",
+    "bottom-start",
+    "bottom-end",
+    "left",
+    "left-start",
+    "left-end",
+    "right",
+    "right-start",
+    "right-end",
+]
+
+#: ``placement`` also accepts ``auto`` (let floating-ui decide) and ``center``
+#: (a modal-like step with no arrow, useful for a welcome step).
+StepPlacement = Literal[
+    "top",
+    "top-start",
+    "top-end",
+    "bottom",
+    "bottom-start",
+    "bottom-end",
+    "left",
+    "left-start",
+    "left-end",
+    "right",
+    "right-start",
+    "right-end",
+    "auto",
+    "center",
+]
+
+#: The buttons rendered in the tooltip footer, in order.
+ButtonType = Literal["back", "close", "primary", "skip"]
+
+#: What opens the tooltip when the beacon is shown.
+BeaconTrigger = Literal["click", "hover"]
+
+#: What the close button does.
+CloseButtonAction = Literal["close", "skip", "replay"]
+
+#: What the ESC key does (``False`` disables it).
+DismissKeyAction = Literal["close", "next", "replay"]
+
+#: What a click on the overlay does (``False`` disables it).
+OverlayClickAction = Literal["close", "next", "replay"]
+
+#: Positioning strategy used by floating-ui.
+Strategy = Literal["absolute", "fixed"]
+
+PLACEMENTS: Final = (
+    "top",
+    "top-start",
+    "top-end",
+    "bottom",
+    "bottom-start",
+    "bottom-end",
+    "left",
+    "left-start",
+    "left-end",
+    "right",
+    "right-start",
+    "right-end",
+    "auto",
+    "center",
+)

reflex_react_joyride/events.py

@@ -0,0 +1,73 @@
+"""The payloads delivered to the component's event triggers.
+
+react-joyride's own ``onEvent`` callback receives the merged step object, which
+carries React nodes and functions and cannot cross the wire. The JSX wrapper
+therefore reduces it to the flat, JSON-safe :class:`JoyrideEvent` below, with
+``snake_case`` keys so it reads naturally from Python::
+
+    @rx.event
+    def on_tour_event(self, event: rjr.JoyrideEvent):
+        self.log.append(f"{event['type']} -> step {event['index'] + 1}")
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class JoyrideEvent(TypedDict):
+    """The payload of every event trigger.
+
+    It is a plain ``dict`` at runtime, so annotate handlers with ``dict`` if you
+    prefer: ``def handler(self, event: dict)``.
+    """
+
+    # The event that fired, e.g. "tour:start" or "step:after". See EVENTS.
+    type: str
+    # The action that triggered it, e.g. "next", "prev", "close". See ACTIONS.
+    action: str
+    # The index of the current step, zero-based.
+    index: int
+    # The total number of steps.
+    size: int
+    # The tour status: idle, ready, waiting, running, paused, skipped, finished.
+    status: str
+    # The step's rendering phase: init, ready, beacon, tooltip, complete, ...
+    lifecycle: str
+    # Which control triggered the action ("button_primary", "overlay", ...), or None.
+    origin: str | None
+    # Whether the tour is running in controlled mode (``step_index`` is set).
+    controlled: bool
+    # Whether the tour is waiting for a target to appear or a hook to resolve.
+    waiting: bool
+    # Whether the page is being scrolled to the target right now.
+    scrolling: bool
+    # ``index == size - 1``.
+    is_last_step: bool
+    # The current step's ``id``, if it has one.
+    step_id: str | None
+    # The current step's ``target`` when it is a CSS selector.
+    step_target: str | None
+    # The current step's ``title`` when it is a plain string.
+    step_title: str | None
+    # The current step's ``data``, passed through untouched.
+    step_data: Any | None
+    # The error message for "error" events, otherwise None.
+    error: str | None
+
+
+class TourState(TypedDict):
+    """The tour state returned by :func:`reflex_react_joyride.actions.get_state`."""
+
+    action: str
+    controlled: bool
+    index: int
+    lifecycle: str
+    origin: str | None
+    scrolling: bool
+    size: int
+    status: str
+    waiting: bool
+
+
+__all__ = ["JoyrideEvent", "TourState"]