@lynx-js/react 0.105.0

package/runtime/src/lynx-api.ts

@@ -0,0 +1,374 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { render } from 'preact';
+import { createContext, createElement } from 'preact/compat';
+import { useState } from 'preact/hooks';
+import type { Consumer, FC, ReactNode } from 'react';
+
+import { factory, withInitDataInState } from './compat/initData.js';
+import { LifecycleConstant } from './lifecycleConstant.js';
+import { flushDelayedLifecycleEvents } from './lynx/tt.js';
+import { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.js';
+import { __root } from './root.js';
+
+/**
+ * The default root exported by `@lynx-js/react` for you to render a JSX
+ * @public
+ */
+export interface Root {
+  /**
+   * Use this API to pass in your JSX to render
+   *
+   * @example
+   *
+   * ```ts
+   * import { root } from "@lynx-js/react"
+   *
+   * function App() {
+   *   // Your app
+   *   return <view>...</view>
+   * }
+   *
+   * root.render(<App/>);
+   * ```
+   *
+   * @example
+   *
+   * ```tsx
+   * import { root } from "@lynx-js/react"
+   *
+   * function App() {
+   *   // Your app
+   *   return <view>...</view>
+   * }
+   *
+   * if (__LEPUS__) {
+   *   root.render(
+   *     <DataProvider data={DEFAULT_DATA}>
+   *        <App/>
+   *     </DataProvider>
+   *   );
+   * } else if (__JS__) {
+   *   fetchData().then((data) => {
+   *     root.render(
+   *       <DataProvider data={data}>
+   *          <App/>
+   *       </DataProvider>
+   *     ); // You can render later after your data is ready
+   *   })
+   * }
+   * ```
+   *
+   * @public
+   */
+  render: (jsx: ReactNode) => void;
+  /**
+   * {@inheritDoc Lynx.registerDataProcessors}
+   * @deprecated use {@link Lynx.registerDataProcessors | lynx.registerDataProcessors} instead
+   * @public
+   */
+  registerDataProcessors: (dataProcessorDefinition: DataProcessorDefinition) => void;
+}
+
+/**
+ * The default and only root of ReactLynx for you to render JSX
+ * @example
+ * ```ts
+ * import { root } from "@lynx-js/react"
+ * ```
+ *
+ * @public
+ */
+export const root: Root = {
+  render: (jsx: ReactNode): void => {
+    if (__LEPUS__) {
+      __root.__jsx = jsx;
+    } else {
+      __root.__jsx = jsx;
+      render(jsx, __root as any);
+      if (__FIRST_SCREEN_SYNC_TIMING__ === 'immediately') {
+      } else {
+        lynx.getNativeApp().callLepusMethod(LifecycleConstant.jsReady, {});
+      }
+
+      flushDelayedLifecycleEvents();
+    }
+  },
+  registerDataProcessors: (dataProcessorDefinition: DataProcessorDefinition): void => {
+    lynx.registerDataProcessors(dataProcessorDefinition);
+  },
+};
+
+const _InitData = /* @__PURE__ */ factory<InitData>(
+  {
+    createContext,
+    useState,
+    createElement,
+    useLynxGlobalEventListener,
+  } as any,
+  '__initData',
+  'onDataChanged',
+);
+/**
+ * The {@link https://react.dev/reference/react/createContext#provider | Provider} Component that provide `initData`,
+ * you must wrap your JSX inside it
+ * @group Components
+ *
+ * @example
+ *
+ * ```ts
+ * import { root } from "@lynx-js/react"
+ *
+ * function App() {
+ *   return (
+ *     <InitDataConsumer children={(initData) => <view>...</view>}/>
+ *   )
+ * }
+ *
+ * root.render(
+ *   <InitDataProvider>
+ *      <App/>
+ *   </InitDataProvider>
+ * );
+ *
+ * ```
+ *
+ * @public
+ */
+export const InitDataProvider: FC<{ children?: ReactNode | undefined }> = /* @__PURE__ */ _InitData.Provider();
+/**
+ * The {@link https://react.dev/reference/react/createContext#consumer | Consumer} Component that provide `initData`.
+ * This should be used with {@link InitDataProvider}
+ * @group Components
+ * @public
+ */
+export const InitDataConsumer: Consumer<InitData> = /* @__PURE__ */ _InitData.Consumer();
+/**
+ * A React Hooks for you to get `initData`.
+ * If `initData` is changed, a re-render will be triggered automatically.
+ *
+ * @example
+ *
+ * ```ts
+ * function App() {
+ *   const initData = useInitData();
+ *
+ *   initData.someProperty // use it
+ * }
+ * ```
+ *
+ * @public
+ */
+export const useInitData: () => InitData = /* @__PURE__ */ _InitData.use();
+/**
+ * A React Hooks for you to get notified when `initData` changed.
+ *
+ * @example
+ * ```ts
+ * function App() {
+ *   useInitDataChanged((data) => {
+ *     data.someProperty // can use it
+ *   })
+ * }
+ * ```
+ * @public
+ */
+export const useInitDataChanged: (callback: (data: InitData) => void) => void = /* @__PURE__ */ _InitData.useChanged();
+
+// const {
+//   Provider: GlobalPropsProvider,
+//   Consumer: GlobalPropsConsumer,
+//   // InitDataContext,
+//   use: useGlobalProps,
+//   useChanged: useGlobalPropsChanged,
+// } = /* @__PURE__ */ factory(
+//   {
+//     createContext,
+//     useState,
+//     useEffect,
+//     createElement,
+//   } as any,
+//   "__globalProps",
+//   "onGlobalPropsChanged"
+// );
+
+// export { GlobalPropsProvider, GlobalPropsConsumer, useGlobalProps, useGlobalPropsChanged };
+
+/**
+ * The interface you can extends so that the `defaultDataProcessor` parameter can be customized
+ *
+ * Should be used with `lynx.registerDataProcessors`. See more examples at {@link Lynx.registerDataProcessors}.
+ *
+ * @public
+ */
+export interface InitDataRaw {}
+/**
+ * The interface you can extends so that the `defaultDataProcessor` returning value can be customized
+ *
+ * Should be used with `lynx.registerDataProcessors`. See more examples at {@link Lynx.registerDataProcessors}.
+ *
+ * @public
+ */
+export interface InitData {}
+
+export { withInitDataInState };
+
+/**
+ * Definition of DataProcessor(s)
+ * @public
+ */
+export interface DataProcessorDefinition {
+  /**
+   * You can custom input and output type of `defaultDataProcessor` by extends {@link InitDataRaw} and {@link InitData}
+   *
+   * Should be used with `lynx.registerDataProcessors`. See more examples at {@link Lynx.registerDataProcessors}.
+   *
+   * @param rawInitData - initData passed from native code
+   * @returns
+   * @public
+   */
+  defaultDataProcessor?: (rawInitData: InitDataRaw) => InitData;
+  /**
+   * Should be used with `lynx.registerDataProcessors`. See more examples at {@link Lynx.registerDataProcessors}.
+   *
+   * @public
+   */
+  dataProcessors?: Record<string, Function>;
+}
+
+/**
+ * APIs under `lynx` global variable that added by ReactLynx.
+ *
+ * @example
+ *
+ * ```ts
+ * lynx.registerDataProcessors(...);
+ * lynx.querySelector(...);
+ * lynx.querySelectorAll(...);
+ * ```
+ *
+ * @public
+ */
+export interface Lynx {
+  /**
+   * An alias of `lynx.getJSModule("GlobalEventEmitter").trigger(eventName, params)` only in Lepus
+   *
+   * @public
+   */
+  triggerGlobalEventFromLepus: (eventName: string, params: any) => void;
+
+  /**
+   * Register DataProcessors. You MUST call this before `root.render()`.
+   *
+   * @example
+   *
+   * You MUST call `lynx.registerDataProcessors` before calling `root.render()`.
+   *
+   * ```ts
+   * import { root } from "@lynx-js/react"
+   *
+   * // You MUST call this before `root.render()`
+   * lynx.registerDataProcessors({
+   *   defaultDataProcessor: () => {...} // default DataProcessor
+   *   dataProcessors: {
+   *     getScreenMetricsOverride: () => {...} // named DataProcessor
+   *   }
+   * })
+   *
+   * root.render(<App/>);
+   * ```
+   *
+   * @example
+   *
+   * If you have a class component with `static defaultDataProcessor`
+   * or `static dataProcessors`, you can use it to register DataProcessors.
+   *
+   * ```ts
+   * import { root, Component } from "@lynx-js/react"
+   *
+   * class App extends Component {
+   *   static defaultDataProcessor() {
+   *      ...
+   *   }
+   *
+   *   static dataProcessors = {
+   *     getScreenMetricsOverride() {
+   *       ...
+   *     }
+   *   }
+   * }
+   *
+   * lynx.registerDataProcessors(App); // You can pass `App` because it has the required shape
+   * root.render(<App/>);
+   * ```
+   *
+   * @example
+   *
+   * For developers who want fully typed `defaultDataProcessor`,
+   * they can achieve it by extends interface `InitDataRaw` and `InitData`.
+   *
+   * ```ts
+   * import { root } from "@lynx-js/react"
+   *
+   * interface ExistingInterface {
+   *   somePropertyFromExistingInterface: number
+   * }
+   *
+   * declare module '@lynx-js/react' {
+   *   interface InitDataRaw extends ExistingInterface {
+   *     someAnotherCustomProperty: string
+   *   }
+   * }
+   *
+   * lynx.registerDataProcessors({
+   *   defaultDataProcessor: (initDataRaw) => {
+   *     initDataRaw.somePropertyFromExistingInterface // will be typed
+   *   }
+   * })
+   *
+   * ```
+   *
+   * @example
+   *
+   * For developers who want fully typed `defaultDataProcessor`,
+   * they can achieve it by extends interface `InitDataRaw` and `InitData`.
+   *
+   * ```ts
+   * import { root, useInitData } from "@lynx-js/react"
+   *
+   * interface AnotherExistingInterface {
+   *   someAnotherPropertyFromExistingInterface: number
+   * }
+   *
+   * declare module '@lynx-js/react' {
+   *   interface InitData extends AnotherExistingInterface {
+   *     someCustomProperty: string
+   *   }
+   * }
+   *
+   * root.registerDataProcessors({
+   *   defaultDataProcessor: () => {
+   *     return {
+   *       someCustomProperty: 'value', // will be typed
+   *       someAnotherPropertyFromExistingInterface: 1, // will be typed
+   *     }
+   *   }
+   * })
+   *
+   * function App() {
+   *   const initData = useInitData();
+   *
+   *   initData.someCustomProperty // will be typed
+   *   initData.someAnotherPropertyFromExistingInterface // will be typed
+   * }
+   *
+   * ```
+   * @public
+   */
+  registerDataProcessors: (dataProcessorDefinition: DataProcessorDefinition) => void;
+}
+
+export { runOnBackground, runOnMainThread } from './worklet/runWorklet.js';
+export { MainThreadRef, useMainThreadRef } from './worklet/workletRef.js';
+export { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.js';

package/runtime/src/lynx.ts

@@ -0,0 +1,105 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { options } from 'preact';
+import type { VNode } from 'preact';
+// to make sure preact's hooks to register earlier than ours
+import './hooks/react.js';
+
+import { initProfileHook } from './debug/profile.js';
+import { document, setupBackgroundDocument } from './document.js';
+import { initDelayUnmount } from './lifecycle/delayUnmount.js';
+import { injectUpdatePatch, replaceCommitHook, replaceRequestAnimationFrame } from './lifecycle/patchUpdate.js';
+import { injectCalledByNative } from './lynx/calledByNative.js';
+import { setupLynxEnv } from './lynx/env.js';
+import { injectLepusMethods } from './lynx/injectLepusMethods.js';
+import { initTimingAPI } from './lynx/performance.js';
+import { injectTt } from './lynx/tt.js';
+import { COMPONENT, DIFF, DIFFED, FORCE } from './renderToOpcodes/constants.js';
+
+// @ts-expect-error Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature
+if (__LEPUS__ && typeof globalThis.processEvalResult === 'undefined') {
+  // @ts-expect-error Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature
+  globalThis.processEvalResult = <T>(result: (schema: string) => T, schema: string) => {
+    return result(schema);
+  };
+}
+
+export function runWithForce(cb: () => void): void {
+  // save vnode and its `_component` in WeakMap
+  const m = new WeakMap<VNode, any>();
+
+  const oldDiff = options[DIFF];
+
+  options[DIFF] = (vnode: VNode) => {
+    if (oldDiff) {
+      oldDiff(vnode);
+    }
+
+    // when `options[DIFF]` is called, a newVnode is passed in
+    // so its `vnode[COMPONENT]` should be null,
+    // but it will be set later
+    Object.defineProperty(vnode, COMPONENT, {
+      configurable: true,
+      set(c) {
+        m.set(vnode, c);
+        if (c) {
+          c[FORCE] = true;
+        }
+      },
+      get() {
+        return m.get(vnode);
+      },
+    });
+  };
+
+  const oldDiffed = options[DIFFED];
+
+  options[DIFFED] = (vnode: VNode) => {
+    if (oldDiffed) {
+      oldDiffed(vnode);
+    }
+
+    // delete is a reverse operation of previous `Object.defineProperty`
+    delete vnode[COMPONENT];
+    // restore
+    vnode[COMPONENT] = m.get(vnode);
+  };
+
+  try {
+    cb();
+  } finally {
+    options[DIFF] = oldDiff as (vnode: VNode) => void;
+    options[DIFFED] = oldDiffed as (vnode: VNode) => void;
+  }
+}
+
+if (__LEPUS__) {
+  injectCalledByNative();
+  injectUpdatePatch();
+  if (__DEV__) {
+    injectLepusMethods();
+  }
+}
+
+// TODO: replace this with __PROFILE__
+if (__PROFILE__) {
+  // We are profiling both main-thread and background.
+  initProfileHook();
+}
+
+if (__JS__) {
+  options.document = document;
+  setupBackgroundDocument();
+  injectTt();
+
+  if (process.env['NODE_ENV'] === 'test') {}
+  else {
+    replaceCommitHook();
+    replaceRequestAnimationFrame();
+    initTimingAPI();
+    initDelayUnmount();
+  }
+}
+
+setupLynxEnv();

package/runtime/src/opcodes.ts

@@ -0,0 +1,64 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { CHILDREN } from './renderToOpcodes/constants.js';
+import { SnapshotInstance } from './snapshot.js';
+
+const enum Opcode {
+  Begin = 0,
+  End,
+  Attr,
+  Text,
+}
+
+export function renderOpcodesInto(opcodes: any[], into: SnapshotInstance): void {
+  let top: SnapshotInstance = into;
+  const stack: SnapshotInstance[] = [into];
+  for (let i = 0; i < opcodes.length;) {
+    const opcode = opcodes[i];
+    switch (opcode) {
+      case Opcode.Begin: {
+        const p = top;
+        top = opcodes[i + 1];
+        // @ts-ignore
+        if (top.__parent) {
+          // already inserted
+          top = new SnapshotInstance(top.type);
+        }
+        p.insertBefore(top);
+        stack.push(top);
+
+        i += 2;
+        break;
+      }
+      case Opcode.End: {
+        // @ts-ignore
+        top[CHILDREN] = undefined;
+
+        stack.pop();
+        const p = stack[stack.length - 1];
+        top = p!;
+
+        i += 1;
+        break;
+      }
+      case Opcode.Attr: {
+        const key = opcodes[i + 1];
+        const value = opcodes[i + 2];
+        top.setAttribute(key, value);
+
+        i += 3;
+        break;
+      }
+      case Opcode.Text: {
+        const text = opcodes[i + 1];
+        const s = new SnapshotInstance(null as unknown as string);
+        s.setAttribute(0, text);
+        top.insertBefore(s);
+
+        i += 2;
+        break;
+      }
+    }
+  }
+}

package/runtime/src/renderToOpcodes/constants.ts

@@ -0,0 +1,24 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export const DIFF = '__b';
+export const RENDER = '__r';
+export const DIFFED = 'diffed';
+export const COMMIT = '__c';
+export const SKIP_EFFECTS = '__s';
+export const CATCH_ERROR = '__e';
+
+// VNode properties
+export const COMPONENT = '__c';
+export const CHILDREN = '__k';
+export const PARENT = '__';
+export const MASK = '__m';
+
+// Component properties
+export const VNODE = '__v';
+export const DIRTY = '__d';
+export const FORCE = '__e';
+export const NEXT_STATE = '__s';
+export const CHILD_DID_SUSPEND = '__c';
+export const RENDER_CALLBACKS = '__h';
+export const HOOK = '__h';