- 
-
-
-
- Video description
-Video description
-Video description
-Video description
--Here you'll learn the various features of `reactpy-router` and how to use them. These examples will utilize the [`reactpy_router.simple.router`][src.reactpy_router.simple.router]. +Here you'll learn the various features of `reactpy-router` and how to use them. These examples will utilize the [`reactpy_router.browser_router`][reactpy_router.browser_router].
@@ -39,7 +39,7 @@ The first step is to create a basic router that will display the home page when {% include "../../examples/python/basic-routing.py" %} ``` -When navigating to [`http://127.0.0.1:8000``](http://127.0.0.1:8000) you should see `Home Page đ `. However, if you go to any other route you will instead see `Missing Link đâđĨ`. +When navigating to [`http://127.0.0.1:8000`](http://127.0.0.1:8000) you should see `Home Page đ `. However, if you go to any other route you will instead see `Missing Link đâđĨ`. With this foundation you can start adding more routes. diff --git a/docs/src/reference/components.md b/docs/src/reference/components.md new file mode 100644 index 0000000..f1cc570 --- /dev/null +++ b/docs/src/reference/components.md @@ -0,0 +1,4 @@ +::: reactpy_router + + options: + members: ["route", "link"] diff --git a/docs/src/reference/core.md b/docs/src/reference/core.md deleted file mode 100644 index 26cf9e5..0000000 --- a/docs/src/reference/core.md +++ /dev/null @@ -1 +0,0 @@ -::: src.reactpy_router.core diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md new file mode 100644 index 0000000..d3cfa18 --- /dev/null +++ b/docs/src/reference/hooks.md @@ -0,0 +1,4 @@ +::: reactpy_router + + options: + members: ["use_params", "use_search_params"] diff --git a/docs/src/reference/router.md b/docs/src/reference/router.md index 2fcea59..5700cf5 100644 --- a/docs/src/reference/router.md +++ b/docs/src/reference/router.md @@ -1 +1,4 @@ -::: src.reactpy_router.simple +::: reactpy_router + + options: + members: ["browser_router"] diff --git a/docs/src/reference/types.md b/docs/src/reference/types.md index 0482432..204bee7 100644 --- a/docs/src/reference/types.md +++ b/docs/src/reference/types.md @@ -1 +1 @@ -::: src.reactpy_router.types +::: reactpy_router.types diff --git a/noxfile.py b/noxfile.py index 1eebea2..6376072 100644 --- a/noxfile.py +++ b/noxfile.py @@ -33,7 +33,6 @@ def test_types(session: Session) -> None: @session(tags=["test"]) def test_style(session: Session) -> None: install_requirements_file(session, "check-style") - session.run("black", ".", "--check") session.run("ruff", "check", ".") diff --git a/pyproject.toml b/pyproject.toml index 763f3a0..d6a0110 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,11 +9,9 @@ warn_redundant_casts = true warn_unused_ignores = true check_untyped_defs = true -[tool.ruff.isort] -known-first-party = ["src", "tests"] - [tool.ruff] -ignore = ["E501"] +lint.ignore = ["E501"] +lint.isort.known-first-party = ["src", "tests"] extend-exclude = [".venv/*", ".eggs/*", ".nox/*", "build/*"] line-length = 120 diff --git a/requirements/check-style.txt b/requirements/check-style.txt index e4f6562..af3ee57 100644 --- a/requirements/check-style.txt +++ b/requirements/check-style.txt @@ -1,2 +1 @@ -black >=23,<24 ruff diff --git a/src/js/package-lock.json b/src/js/package-lock.json index db77c4d..c98d3c6 100644 --- a/src/js/package-lock.json +++ b/src/js/package-lock.json @@ -6,7 +6,6 @@ "": { "name": "reactpy-router", "dependencies": { - "htm": "^3.0.4", "react": "^17.0.1", "react-dom": "^17.0.1" }, @@ -1098,11 +1097,6 @@ "url": "https://github.com/sponsors/ljharb" } }, - "node_modules/htm": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/htm/-/htm-3.1.0.tgz", - "integrity": "sha512-L0s3Sid5r6YwrEvkig14SK3Emmc+kIjlfLhEGn2Vy3bk21JyDEes4MoDsbJk6luaPp8bugErnxPz86ZuAw6e5Q==" - }, "node_modules/ignore": { "version": "5.2.4", "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", @@ -3126,11 +3120,6 @@ "has-symbols": "^1.0.2" } }, - "htm": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/htm/-/htm-3.1.0.tgz", - "integrity": "sha512-L0s3Sid5r6YwrEvkig14SK3Emmc+kIjlfLhEGn2Vy3bk21JyDEes4MoDsbJk6luaPp8bugErnxPz86ZuAw6e5Q==" - }, "ignore": { "version": "5.2.4", "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", diff --git a/src/js/package.json b/src/js/package.json index 9baef8c..d4ac92c 100644 --- a/src/js/package.json +++ b/src/js/package.json @@ -18,16 +18,15 @@ "test": "echo \"Error: no test specified\" && exit 1" }, "devDependencies": { - "prettier": "^2.2.1", "eslint": "^8.38.0", "eslint-plugin-react": "^7.32.2", + "prettier": "^2.2.1", "rollup": "^2.35.1", "rollup-plugin-commonjs": "^10.1.0", "rollup-plugin-node-resolve": "^5.2.0", "rollup-plugin-replace": "^2.2.0" }, "dependencies": { - "htm": "^3.0.4", "react": "^17.0.1", "react-dom": "^17.0.1" } diff --git a/src/js/rollup.config.js b/src/js/rollup.config.js index ab1d0b1..396fd87 100644 --- a/src/js/rollup.config.js +++ b/src/js/rollup.config.js @@ -5,7 +5,7 @@ import replace from "rollup-plugin-replace"; export default { input: "src/index.js", output: { - file: "../reactpy_router/bundle.js", + file: "../reactpy_router/static/bundle.js", format: "esm", }, plugins: [ diff --git a/src/js/src/index.js b/src/js/src/index.js index 1f43092..8ead7eb 100644 --- a/src/js/src/index.js +++ b/src/js/src/index.js @@ -1,8 +1,5 @@ import React from "react"; import ReactDOM from "react-dom"; -import htm from "htm"; - -const html = htm.bind(React.createElement); export function bind(node) { return { @@ -15,30 +12,69 @@ export function bind(node) { }; } -export function History({ onChange }) { - // capture changes to the browser's history +export function History({ onHistoryChange }) { + // Capture browser "history go back" action and tell the server about it + // Note: Browsers do not allow us to detect "history go forward" actions. React.useEffect(() => { + // Register a listener for the "popstate" event and send data back to the server using the `onHistoryChange` callback. const listener = () => { - onChange({ + onHistoryChange({ pathname: window.location.pathname, search: window.location.search, }); }; + + // Register the event listener window.addEventListener("popstate", listener); + + // Delete the event listener when the component is unmounted return () => window.removeEventListener("popstate", listener); }); - return null; -} -export function Link({ to, onClick, children, ...props }) { - const handleClick = (event) => { - event.preventDefault(); - window.history.pushState({}, to, new URL(to, window.location)); - onClick({ + // Tell the server about the URL during the initial page load + // FIXME: This currently runs every time any component is mounted due to a ReactPy core rendering bug. + // https://github.com/reactive-python/reactpy/pull/1224 + React.useEffect(() => { + onHistoryChange({ pathname: window.location.pathname, search: window.location.search, }); - }; + return () => {}; + }, []); + return null; +} - return html`${children}`; +// FIXME: The Link component is unused due to a ReactPy core rendering bug +// which causes duplicate rendering (and thus duplicate event listeners). +// https://github.com/reactive-python/reactpy/pull/1224 +export function Link({ onClick, linkClass }) { + // This component is not the actual anchor link. + // It is an event listener for the link component created by ReactPy. + React.useEffect(() => { + // Event function that will tell the server about clicks + const handleClick = (event) => { + event.preventDefault(); + let to = event.target.getAttribute("href"); + window.history.pushState({}, to, new URL(to, window.location)); + onClick({ + pathname: window.location.pathname, + search: window.location.search, + }); + }; + + // Register the event listener + let link = document.querySelector(`.${linkClass}`); + if (link) { + link.addEventListener("click", handleClick); + } + + // Delete the event listener when the component is unmounted + return () => { + let link = document.querySelector(`.${linkClass}`); + if (link) { + link.removeEventListener("click", handleClick); + } + }; + }); + return null; } diff --git a/src/reactpy_router/__init__.py b/src/reactpy_router/__init__.py index cb2fcbc..fa2781f 100644 --- a/src/reactpy_router/__init__.py +++ b/src/reactpy_router/__init__.py @@ -1,20 +1,16 @@ # the version is statically loaded by setup.py __version__ = "0.1.1" -from . import simple -from .core import create_router, link, route, router_component, use_params, use_query -from .types import Route, RouteCompiler, RouteResolver + +from .components import link, route +from .hooks import use_params, use_search_params +from .routers import browser_router, create_router __all__ = ( "create_router", "link", "route", - "route", - "Route", - "RouteCompiler", - "router_component", - "RouteResolver", - "simple", + "browser_router", "use_params", - "use_query", + "use_search_params", ) diff --git a/src/reactpy_router/components.py b/src/reactpy_router/components.py new file mode 100644 index 0000000..3008065 --- /dev/null +++ b/src/reactpy_router/components.py @@ -0,0 +1,101 @@ +from __future__ import annotations + +from pathlib import Path +from typing import Any +from urllib.parse import urljoin +from uuid import uuid4 + +from reactpy import component, event, html, use_connection +from reactpy.backend.types import Location +from reactpy.core.component import Component +from reactpy.core.types import VdomDict +from reactpy.web.module import export, module_from_file + +from reactpy_router.hooks import _use_route_state +from reactpy_router.types import Route + +History = export( + module_from_file("reactpy-router", file=Path(__file__).parent / "static" / "bundle.js"), + ("History"), +) +"""Client-side portion of history handling""" + +Link = export( + module_from_file("reactpy-router", file=Path(__file__).parent / "static" / "bundle.js"), + ("Link"), +) +"""Client-side portion of link handling""" + +link_js_content = (Path(__file__).parent / "static" / "link.js").read_text(encoding="utf-8") + + +def link(attributes: dict[str, Any], *children: Any) -> Component: + """Create a link with the given attributes and children.""" + return _link(attributes, *children) + + +@component +def _link(attributes: dict[str, Any], *children: Any) -> VdomDict: + """A component that renders a link to the given path.""" + attributes = attributes.copy() + uuid_string = f"link-{uuid4().hex}" + class_name = f"{uuid_string}" + set_location = _use_route_state().set_location + if "className" in attributes: + class_name = " ".join([attributes.pop("className"), class_name]) + if "class_name" in attributes: # pragma: no cover + # TODO: This can be removed when ReactPy stops supporting underscores in attribute names + class_name = " ".join([attributes.pop("class_name"), class_name]) + if "href" in attributes and "to" not in attributes: + attributes["to"] = attributes.pop("href") + if "to" not in attributes: # pragma: no cover + raise ValueError("The `to` attribute is required for the `Link` component.") + to = attributes.pop("to") + + attrs = { + **attributes, + "href": to, + "className": class_name, + } + + # FIXME: This component currently works in a "dumb" way by trusting that ReactPy's script tag \ + # properly sets the location due to bugs in ReactPy rendering. + # https://github.com/reactive-python/reactpy/pull/1224 + current_path = use_connection().location.pathname + + @event(prevent_default=True) + def on_click(_event: dict[str, Any]) -> None: + pathname, search = to.split("?", 1) if "?" in to else (to, "") + if search: + search = f"?{search}" + + # Resolve relative paths that match `../foo` + if pathname.startswith("../"): + pathname = urljoin(current_path, pathname) + + # Resolve relative paths that match `foo` + if not pathname.startswith("/"): + pathname = urljoin(current_path, pathname) + + # Resolve relative paths that match `/foo/../bar` + while "/../" in pathname: + part_1, part_2 = pathname.split("/../", 1) + pathname = urljoin(f"{part_1}/", f"../{part_2}") + + # Resolve relative paths that match `foo/./bar` + pathname = pathname.replace("/./", "/") + + set_location(Location(pathname, search)) + + attrs["onClick"] = on_click + + return html._(html.a(attrs, *children), html.script(link_js_content.replace("UUID", uuid_string))) + + # def on_click(_event: dict[str, Any]) -> None: + # set_location(Location(**_event)) + # return html._(html.a(attrs, *children), Link({"onClick": on_click, "linkClass": uuid_string})) + + +def route(path: str, element: Any | None, *routes: Route) -> Route: + """Create a route with the given path, element, and child routes.""" + return Route(path, element, routes) diff --git a/src/reactpy_router/converters.py b/src/reactpy_router/converters.py new file mode 100644 index 0000000..5fe1b5e --- /dev/null +++ b/src/reactpy_router/converters.py @@ -0,0 +1,37 @@ +import uuid + +from reactpy_router.types import ConversionInfo + +__all__ = ["CONVERTERS"] + +CONVERTERS: dict[str, ConversionInfo] = { + "int": { + "regex": r"\d+", + "func": int, + }, + "str": { + "regex": r"[^/]+", + "func": str, + }, + "uuid": { + "regex": r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", + "func": uuid.UUID, + }, + "slug": { + "regex": r"[-a-zA-Z0-9_]+", + "func": str, + }, + "path": { + "regex": r".+", + "func": str, + }, + "float": { + "regex": r"\d+(\.\d+)?", + "func": float, + }, + "any": { + "regex": r".*", + "func": str, + }, +} +"""The conversion types supported by the default Resolver.""" diff --git a/src/reactpy_router/core.py b/src/reactpy_router/core.py deleted file mode 100644 index 490a78c..0000000 --- a/src/reactpy_router/core.py +++ /dev/null @@ -1,144 +0,0 @@ -"""Core functionality for the reactpy-router package.""" - -from __future__ import annotations - -from dataclasses import dataclass, replace -from pathlib import Path -from typing import Any, Callable, Iterator, Sequence, TypeVar -from urllib.parse import parse_qs - -from reactpy import ( - component, - create_context, - html, - use_context, - use_location, - use_memo, - use_state, -) -from reactpy.backend.hooks import ConnectionContext, use_connection -from reactpy.backend.types import Connection, Location -from reactpy.core.types import VdomChild, VdomDict -from reactpy.types import ComponentType, Context -from reactpy.web.module import export, module_from_file - -from reactpy_router.types import Route, RouteCompiler, Router, RouteResolver - -R = TypeVar("R", bound=Route) - - -def route(path: str, element: Any | None, *routes: Route) -> Route: - """Create a route with the given path, element, and child routes""" - return Route(path, element, routes) - - -def create_router(compiler: RouteCompiler[R]) -> Router[R]: - """A decorator that turns a route compiler into a router""" - - def wrapper(*routes: R) -> ComponentType: - return router_component(*routes, compiler=compiler) - - return wrapper - - -@component -def router_component( - *routes: R, - compiler: RouteCompiler[R], -) -> VdomDict | None: - """A component that renders the first matching route using the given compiler""" - - old_conn = use_connection() - location, set_location = use_state(old_conn.location) - - resolvers = use_memo( - lambda: tuple(map(compiler, _iter_routes(routes))), - dependencies=(compiler, hash(routes)), - ) - - match = use_memo(lambda: _match_route(resolvers, location)) - - if match is not None: - element, params = match - return html._( - ConnectionContext( - _route_state_context(element, value=_RouteState(set_location, params)), - value=Connection(old_conn.scope, location, old_conn.carrier), - ), - _history({"on_change": lambda event: set_location(Location(**event))}), - ) - - return None - - -@component -def link(*children: VdomChild, to: str, **attributes: Any) -> VdomDict: - """A component that renders a link to the given path""" - set_location = _use_route_state().set_location - attrs = { - **attributes, - "to": to, - "onClick": lambda event: set_location(Location(**event)), - } - return _link(attrs, *children) - - -def use_params() -> dict[str, Any]: - """Get parameters from the currently matching route pattern""" - return _use_route_state().params - - -def use_query( - keep_blank_values: bool = False, - strict_parsing: bool = False, - errors: str = "replace", - max_num_fields: int | None = None, - separator: str = "&", -) -> dict[str, list[str]]: - """See :func:`urllib.parse.parse_qs` for parameter info.""" - return parse_qs( - use_location().search[1:], - keep_blank_values=keep_blank_values, - strict_parsing=strict_parsing, - errors=errors, - max_num_fields=max_num_fields, - separator=separator, - ) - - -def _iter_routes(routes: Sequence[R]) -> Iterator[R]: - for parent in routes: - for child in _iter_routes(parent.routes): - yield replace(child, path=parent.path + child.path) # type: ignore[misc] - yield parent - - -def _match_route( - compiled_routes: Sequence[RouteResolver], location: Location -) -> tuple[Any, dict[str, Any]] | None: - for resolver in compiled_routes: - match = resolver.resolve(location.pathname) - if match is not None: - return match - return None - - -_link, _history = export( - module_from_file("reactpy-router", file=Path(__file__).parent / "bundle.js"), - ("Link", "History"), -) - - -@dataclass -class _RouteState: - set_location: Callable[[Location], None] - params: dict[str, Any] - - -def _use_route_state() -> _RouteState: - route_state = use_context(_route_state_context) - assert route_state is not None - return route_state - - -_route_state_context: Context[_RouteState | None] = create_context(None) diff --git a/src/reactpy_router/hooks.py b/src/reactpy_router/hooks.py new file mode 100644 index 0000000..3831acf --- /dev/null +++ b/src/reactpy_router/hooks.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any, Callable +from urllib.parse import parse_qs + +from reactpy import create_context, use_context, use_location +from reactpy.backend.types import Location +from reactpy.types import Context + + +@dataclass +class _RouteState: + set_location: Callable[[Location], None] + params: dict[str, Any] + + +def _use_route_state() -> _RouteState: + route_state = use_context(_route_state_context) + if route_state is None: # pragma: no cover + raise RuntimeError( + "ReactPy-Router was unable to find a route context. Are you " + "sure this hook/component is being called within a router?" + ) + + return route_state + + +_route_state_context: Context[_RouteState | None] = create_context(None) + + +def use_params() -> dict[str, Any]: + """The `use_params` hook returns an object of key/value pairs of the dynamic parameters \ + from the current URL that were matched by the `Route`. Child routes inherit all parameters \ + from their parent routes. + + For example, if you have a `URL_PARAM` defined in the route `/example/