@reactpy/client 0.1.0 → 0.2.0

package/package.json

@@ -1,35 +1,37 @@
 {
   "author": "Ryan Morshead",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "description": "A client for ReactPy implemented in React",
+  "license": "MIT",
+  "name": "@reactpy/client",
+  "type": "module",
+  "version": "0.2.0",
   "dependencies": {
-    "htm": "^3.0.3",
+    "event-to-object": "^0.1.0",
     "json-pointer": "^0.6.2"
   },
-  "description": "A client for ReactPy implemented in React",
   "devDependencies": {
-    "jsdom": "16.5.0",
-    "lodash": "^4.17.21",
-    "prettier": "^2.5.1",
-    "uvu": "^0.5.1"
+    "@types/json-pointer": "^1.0.31",
+    "@types/react": "^17.0",
+    "@types/react-dom": "^17.0",
+    "prettier": "^3.0.0-alpha.6",
+    "typescript": "^4.9.5"
   },
-  "files": [
-    "src/**/*.js"
-  ],
-  "license": "MIT",
-  "main": "src/index.js",
-  "name": "@reactpy/client",
   "peerDependencies": {
-    "react": ">=16",
-    "react-dom": ">=16"
+    "react": ">=16 <18",
+    "react-dom": ">=16 <18"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/reactive-python/reactpy"
   },
   "scripts": {
-    "check-format": "prettier --check ./src ./tests",
-    "format": "prettier --write ./src ./tests",
-    "test": "uvu tests"
-  },
-  "type": "module",
-  "version": "0.1.0"
+    "build": "tsc -b",
+    "format": "prettier --write .",
+    "test": "npm run check:tests",
+    "check:format": "prettier --check .",
+    "check:tests": "echo 'no tests'",
+    "check:types": "tsc --noEmit"
+  }
 }

package/src/components.tsx

@@ -0,0 +1,231 @@
+import React, {
+  createElement,
+  createContext,
+  useState,
+  useRef,
+  useContext,
+  useEffect,
+  Fragment,
+  MutableRefObject,
+  ChangeEvent,
+} from "react";
+// @ts-ignore
+import { set as setJsonPointer } from "json-pointer";
+import { LayoutUpdateMessage } from "./messages";
+import {
+  ReactPyVdom,
+  ReactPyComponent,
+  createChildren,
+  createAttributes,
+  loadImportSource,
+  ImportSourceBinding,
+} from "./reactpy-vdom";
+import { ReactPyClient } from "./reactpy-client";
+
+const ClientContext = createContext<ReactPyClient>(null as any);
+
+export function Layout(props: { client: ReactPyClient }): JSX.Element {
+  const currentModel: ReactPyVdom = useState({ tagName: "" })[0];
+  const forceUpdate = useForceUpdate();
+
+  useEffect(() => {
+    props.client.onMessage<LayoutUpdateMessage>(
+      "layout-update",
+      ({ path, model }) => {
+        if (path === "") {
+          Object.assign(currentModel, model);
+        } else {
+          setJsonPointer(currentModel, path, model);
+        }
+        forceUpdate();
+      },
+    );
+    props.client.start();
+    return () => props.client.stop();
+  }, [currentModel, props.client]);
+
+  return (
+    <ClientContext.Provider value={props.client}>
+      <Element model={currentModel} />
+    </ClientContext.Provider>
+  );
+}
+
+export function Element({ model }: { model: ReactPyVdom }): JSX.Element | null {
+  if (model.error !== undefined) {
+    if (model.error) {
+      return <pre>{model.error}</pre>;
+    } else {
+      return null;
+    }
+  }
+
+  let SpecializedElement: ReactPyComponent;
+  if (model.tagName in SPECIAL_ELEMENTS) {
+    SpecializedElement =
+      SPECIAL_ELEMENTS[model.tagName as keyof typeof SPECIAL_ELEMENTS];
+  } else if (model.importSource) {
+    SpecializedElement = ImportedElement;
+  } else {
+    SpecializedElement = StandardElement;
+  }
+
+  return <SpecializedElement model={model} />;
+}
+
+function StandardElement({ model }: { model: ReactPyVdom }) {
+  const client = React.useContext(ClientContext);
+  // Use createElement here to avoid warning about variable numbers of children not
+  // having keys. Warning about this must now be the responsibility of the client
+  // providing the models instead of the client rendering them.
+  return createElement(
+    model.tagName === "" ? Fragment : model.tagName,
+    createAttributes(model, client),
+    ...createChildren(model, (child) => {
+      return <Element model={child} key={child.key} />;
+    }),
+  );
+}
+
+function UserInputElement({ model }: { model: ReactPyVdom }): JSX.Element {
+  const client = useContext(ClientContext);
+  const props = createAttributes(model, client);
+  const [value, setValue] = React.useState(props.value);
+
+  // honor changes to value from the client via props
+  React.useEffect(() => setValue(props.value), [props.value]);
+
+  const givenOnChange = props.onChange;
+  if (typeof givenOnChange === "function") {
+    props.onChange = (event: ChangeEvent<any>) => {
+      // immediately update the value to give the user feedback
+      setValue(event.target.value);
+      // allow the client to respond (and possibly change the value)
+      givenOnChange(event);
+    };
+  }
+
+  // Use createElement here to avoid warning about variable numbers of children not
+  // having keys. Warning about this must now be the responsibility of the client
+  // providing the models instead of the client rendering them.
+  return createElement(
+    model.tagName,
+    // overwrite
+    { ...props, value },
+    ...createChildren(model, (child) => (
+      <Element model={child} key={child.key} />
+    )),
+  );
+}
+
+function ScriptElement({ model }: { model: ReactPyVdom }) {
+  const ref = useRef<HTMLDivElement | null>(null);
+
+  React.useEffect(() => {
+    if (!ref.current) {
+      return;
+    }
+    const scriptContent = model?.children?.filter(
+      (value): value is string => typeof value == "string",
+    )[0];
+
+    let scriptElement: HTMLScriptElement;
+    if (model.attributes) {
+      scriptElement = document.createElement("script");
+      for (const [k, v] of Object.entries(model.attributes)) {
+        scriptElement.setAttribute(k, v);
+      }
+      if (scriptContent) {
+        scriptElement.appendChild(document.createTextNode(scriptContent));
+      }
+      ref.current.appendChild(scriptElement);
+    } else if (scriptContent) {
+      let scriptResult = eval(scriptContent);
+      if (typeof scriptResult == "function") {
+        return scriptResult();
+      }
+    }
+  }, [model.key, ref.current]);
+
+  return <div ref={ref} />;
+}
+
+function ImportedElement({ model }: { model: ReactPyVdom }) {
+  const importSourceVdom = model.importSource;
+  const importSourceRef = useImportSource(model);
+
+  if (!importSourceVdom) {
+    return null;
+  }
+
+  const importSourceFallback = importSourceVdom.fallback;
+
+  if (!importSourceVdom) {
+    // display a fallback if one was given
+    if (!importSourceFallback) {
+      return null;
+    } else if (typeof importSourceFallback === "string") {
+      return <div>{importSourceFallback}</div>;
+    } else {
+      return <StandardElement model={importSourceFallback} />;
+    }
+  } else {
+    return <div ref={importSourceRef} />;
+  }
+}
+
+function useForceUpdate() {
+  const [, setState] = useState(false);
+  return () => setState((old) => !old);
+}
+
+function useImportSource(model: ReactPyVdom): MutableRefObject<any> {
+  const vdomImportSource = model.importSource;
+
+  const mountPoint = useRef<HTMLElement>(null);
+  const client = React.useContext(ClientContext);
+  const [binding, setBinding] = useState<ImportSourceBinding | null>(null);
+
+  React.useEffect(() => {
+    let unmounted = false;
+
+    if (vdomImportSource) {
+      loadImportSource(vdomImportSource, client).then((bind) => {
+        if (!unmounted && mountPoint.current) {
+          setBinding(bind(mountPoint.current));
+        }
+      });
+    }
+
+    return () => {
+      unmounted = true;
+      if (
+        binding &&
+        vdomImportSource &&
+        !vdomImportSource.unmountBeforeUpdate
+      ) {
+        binding.unmount();
+      }
+    };
+  }, [client, vdomImportSource, setBinding, mountPoint.current]);
+
+  // this effect must run every time in case the model has changed
+  useEffect(() => {
+    if (!(binding && vdomImportSource)) {
+      return;
+    }
+    binding.render(model);
+    if (vdomImportSource.unmountBeforeUpdate) {
+      return binding.unmount;
+    }
+  });
+
+  return mountPoint;
+}
+
+const SPECIAL_ELEMENTS = {
+  input: UserInputElement,
+  script: ScriptElement,
+  select: UserInputElement,
+  textarea: UserInputElement,
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./components";
+export * from "./messages";
+export * from "./mount";
+export * from "./reactpy-client";
+export * from "./reactpy-vdom";

package/src/logger.ts

@@ -0,0 +1,5 @@
+export default {
+  log: (...args: any[]): void => console.log("[ReactPy]", ...args),
+  warn: (...args: any[]): void => console.warn("[ReactPy]", ...args),
+  error: (...args: any[]): void => console.error("[ReactPy]", ...args),
+};

package/src/messages.ts

@@ -0,0 +1,32 @@
+import { ReactPyVdom } from "./reactpy-vdom";
+
+export interface IMessage {
+  type: string;
+}
+
+export type ConnectionOpenMessage = {
+  type: "connection-open";
+};
+
+export type ConnectionCloseMessage = {
+  type: "connection-close";
+};
+
+export type LayoutUpdateMessage = {
+  type: "layout-update";
+  path: string;
+  model: ReactPyVdom;
+};
+
+export type LayoutEventMessage = {
+  type: "layout-event";
+  target: string;
+  data: any;
+};
+
+export type IncomingMessage =
+  | LayoutUpdateMessage
+  | ConnectionOpenMessage
+  | ConnectionCloseMessage;
+export type OutgoingMessage = LayoutEventMessage;
+export type Message = IncomingMessage | OutgoingMessage;

package/src/mount.tsx

@@ -0,0 +1,8 @@
+import React from "react";
+import { render } from "react-dom";
+import { Layout } from "./components";
+import { ReactPyClient } from "./reactpy-client";
+
+export function mount(element: HTMLElement, client: ReactPyClient): void {
+  render(<Layout client={client} />, element);
+}

package/src/reactpy-client.ts

@@ -0,0 +1,274 @@
+import { OutgoingMessage, IncomingMessage } from "./messages";
+import { ReactPyModule } from "./reactpy-vdom";
+import logger from "./logger";
+
+/**
+ * A client for communicating with a ReactPy server.
+ */
+export interface ReactPyClient {
+  /**
+   * Connect to the server and start receiving messages.
+   *
+   * Message handlers should be registered before calling this method in order to
+   * garuntee that messages are not missed.
+   */
+  start: () => void;
+  /**
+   * Disconnect from the server and stop receiving messages.
+   */
+  stop: () => void;
+  /**
+   * Register a handler for a message type.
+   */
+  onMessage: <M extends IncomingMessage>(
+    type: M["type"],
+    handler: (message: M) => void,
+  ) => void;
+  /**
+   * Send a message to the server.
+   */
+  sendMessage: (message: OutgoingMessage) => void;
+  /**
+   * Dynamically load a module from the server.
+   */
+  loadModule: (moduleName: string) => Promise<ReactPyModule>;
+}
+
+export type SimpleReactPyClientProps = {
+  serverLocation?: LocationProps;
+  reconnectOptions?: ReconnectProps;
+};
+
+/**
+ * The location of the server.
+ *
+ * This is used to determine the location of the server's API endpoints. All endpoints
+ * are expected to be found at the base URL, with the following paths:
+ *
+ * - `_reactpy/stream/${route}${query}`: The websocket endpoint for the stream.
+ * - `_reactpy/modules`: The directory containing the dynamically loaded modules.
+ * - `_reactpy/assets`: The directory containing the static assets.
+ */
+type LocationProps = {
+  /**
+   * The base URL of the server.
+   *
+   * @default - document.location.origin
+   */
+  url: string;
+  /**
+   * The route to the page being rendered.
+   *
+   * @default - document.location.pathname
+   */
+  route: string;
+  /**
+   * The query string of the page being rendered.
+   *
+   * @default - document.location.search
+   */
+  query: string;
+};
+
+type ReconnectProps = {
+  maxInterval?: number;
+  maxRetries?: number;
+  backoffRate?: number;
+  intervalJitter?: number;
+};
+
+export class SimpleReactPyClient implements ReactPyClient {
+  private resolveShouldOpen: (value: unknown) => void;
+  private resolveShouldClose: (value: unknown) => void;
+  private readonly urls: ServerUrls;
+  private readonly handlers: {
+    [key in IncomingMessage["type"]]: ((message: any) => void)[];
+  };
+  private readonly socket: { current?: WebSocket };
+
+  constructor(props: SimpleReactPyClientProps) {
+    this.handlers = {
+      "connection-open": [],
+      "connection-close": [],
+      "layout-update": [],
+    };
+
+    this.urls = getServerUrls(
+      props.serverLocation || {
+        url: document.location.origin,
+        route: document.location.pathname,
+        query: document.location.search,
+      },
+    );
+
+    this.resolveShouldOpen = () => {
+      throw new Error("Could not start client");
+    };
+    this.resolveShouldClose = () => {
+      throw new Error("Could not stop client");
+    };
+    const shouldOpen = new Promise((r) => (this.resolveShouldOpen = r));
+    const shouldClose = new Promise((r) => (this.resolveShouldClose = r));
+
+    this.socket = startReconnectingWebSocket({
+      shouldOpen,
+      shouldClose,
+      url: this.urls.stream,
+      onOpen: () => this.handleIncoming({ type: "connection-open" }),
+      onMessage: async ({ data }) => this.handleIncoming(JSON.parse(data)),
+      onClose: () => this.handleIncoming({ type: "connection-close" }),
+      ...props.reconnectOptions,
+    });
+  }
+
+  start(): void {
+    logger.log("starting client...");
+    this.resolveShouldOpen(undefined);
+  }
+
+  stop(): void {
+    logger.log("stopping client...");
+    this.resolveShouldClose(undefined);
+  }
+
+  onMessage<M extends IncomingMessage>(
+    type: M["type"],
+    handler: (message: M) => void,
+  ): void {
+    this.handlers[type].push(handler);
+  }
+
+  sendMessage(message: OutgoingMessage): void {
+    this.socket.current?.send(JSON.stringify(message));
+  }
+
+  loadModule(moduleName: string): Promise<ReactPyModule> {
+    return import(`${this.urls.modules}/${moduleName}`);
+  }
+
+  private handleIncoming(message: IncomingMessage): void {
+    if (!message.type) {
+      logger.warn("Received message without type", message);
+      return;
+    }
+
+    const messageHandlers: ((m: any) => void)[] | undefined =
+      this.handlers[message.type];
+    if (!messageHandlers) {
+      logger.warn("Received message without handler", message);
+      return;
+    }
+
+    messageHandlers.forEach((h) => h(message));
+  }
+}
+
+type ServerUrls = {
+  base: URL;
+  stream: string;
+  modules: string;
+  assets: string;
+};
+
+function getServerUrls(props: LocationProps): ServerUrls {
+  const base = new URL(`${props.url || document.location.origin}/_reactpy`);
+  const modules = `${base}/modules`;
+  const assets = `${base}/assets`;
+
+  const streamProtocol = `ws${base.protocol === "https:" ? "s" : ""}`;
+  const streamPath = rtrim(`${base.pathname}/stream${props.route || ""}`, "/");
+  const stream = `${streamProtocol}://${base.host}${streamPath}${props.query}`;
+
+  return { base, modules, assets, stream };
+}
+
+function startReconnectingWebSocket(
+  props: {
+    shouldOpen: Promise<any>;
+    shouldClose: Promise<any>;
+    url: string;
+    onOpen: () => void;
+    onMessage: (message: MessageEvent<any>) => void;
+    onClose: () => void;
+  } & ReconnectProps,
+) {
+  const {
+    maxInterval = 60000,
+    maxRetries = 50,
+    backoffRate = 1.1,
+    intervalJitter = 0.1,
+  } = props;
+
+  const startInterval = 750;
+  let retries = 0;
+  let interval = startInterval;
+  let closed = false;
+  let everConnected = false;
+  const socket: { current?: WebSocket } = {};
+
+  const connect = () => {
+    if (closed) {
+      return;
+    }
+    socket.current = new WebSocket(props.url);
+    socket.current.onopen = () => {
+      everConnected = true;
+      logger.log("client connected");
+      interval = startInterval;
+      retries = 0;
+      props.onOpen();
+    };
+    socket.current.onmessage = props.onMessage;
+    socket.current.onclose = () => {
+      if (!everConnected) {
+        logger.log("failed to connect");
+        return;
+      }
+
+      logger.log("client disconnected");
+      props.onClose();
+
+      if (retries >= maxRetries) {
+        return;
+      }
+
+      const thisInterval = addJitter(interval, intervalJitter);
+      logger.log(
+        `reconnecting in ${(thisInterval / 1000).toPrecision(4)} seconds...`,
+      );
+      setTimeout(connect, thisInterval);
+      interval = nextInterval(interval, backoffRate, maxInterval);
+      retries++;
+    };
+  };
+
+  props.shouldOpen.then(connect);
+  props.shouldClose.then(() => {
+    closed = true;
+    socket.current?.close();
+  });
+
+  return socket;
+}
+
+function nextInterval(
+  currentInterval: number,
+  backoffRate: number,
+  maxInterval: number,
+): number {
+  return Math.min(
+    currentInterval *
+      // increase interval by backoff rate
+      backoffRate,
+    // don't exceed max interval
+    maxInterval,
+  );
+}
+
+function addJitter(interval: number, jitter: number): number {
+  return interval + (Math.random() * jitter * interval * 2 - jitter * interval);
+}
+
+function rtrim(text: string, trim: string): string {
+  return text.replace(new RegExp(`${trim}+$`), "");
+}