@lynx-js/react 0.105.0

package/runtime/src/snapshotPatchApply.ts

@@ -0,0 +1,117 @@
+// 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 { createSnapshot, SnapshotInstance, snapshotInstanceManager, snapshotManager } from './snapshot.js';
+import type { SnapshotPatch } from './snapshotPatch.js';
+import { SnapshotOperation } from './snapshotPatch.js';
+
+function reportCtxNotFound(): void {
+  lynx.reportError(new Error(`snapshotPatchApply failed: ctx not found`));
+}
+
+export function snapshotPatchApply(snapshotPatch: SnapshotPatch): void {
+  const length = snapshotPatch.length;
+  for (let i = 0; i < length; ++i) {
+    switch (snapshotPatch[i]) {
+      case SnapshotOperation.CreateElement: {
+        const type = snapshotPatch[++i];
+        const id = snapshotPatch[++i];
+        new SnapshotInstance(type, id);
+        break;
+      }
+      case SnapshotOperation.InsertBefore: {
+        const parentId = snapshotPatch[++i];
+        const childId = snapshotPatch[++i];
+        const beforeId = snapshotPatch[++i];
+        const parent = snapshotInstanceManager.values.get(parentId);
+        const child = snapshotInstanceManager.values.get(childId);
+        const existingNode = snapshotInstanceManager.values.get(beforeId!);
+        if (!parent || !child) {
+          reportCtxNotFound();
+        } else {
+          parent.insertBefore(child, existingNode);
+        }
+        break;
+      }
+      case SnapshotOperation.RemoveChild: {
+        const parentId = snapshotPatch[++i];
+        const childId = snapshotPatch[++i];
+        const parent = snapshotInstanceManager.values.get(parentId);
+        const child = snapshotInstanceManager.values.get(childId);
+        if (!parent || !child) {
+          reportCtxNotFound();
+        } else {
+          parent.removeChild(child);
+        }
+        break;
+      }
+      case SnapshotOperation.SetAttribute: {
+        const id = snapshotPatch[++i];
+        const dynamicPartIndex = snapshotPatch[++i];
+        const value = snapshotPatch[++i];
+        const si = snapshotInstanceManager.values.get(id);
+        if (si) {
+          si.setAttribute(dynamicPartIndex, value);
+        } else {
+          reportCtxNotFound();
+        }
+        break;
+      }
+      case SnapshotOperation.SetAttributes: {
+        const id = snapshotPatch[++i];
+        const values = snapshotPatch[++i];
+        const si = snapshotInstanceManager.values.get(id);
+        if (si) {
+          si.setAttribute('values', values);
+        } else {
+          reportCtxNotFound();
+        }
+        break;
+      }
+      case SnapshotOperation.DEV_ONLY_AddSnapshot: {
+        if (__DEV__) {
+          const uniqID: string = snapshotPatch[++i];
+          const create: string = snapshotPatch[++i];
+          const update: string[] = snapshotPatch[++i];
+          const slot = snapshotPatch[++i];
+          const cssId: number = snapshotPatch[++i] ?? 0;
+          const entryName: string | undefined = snapshotPatch[++i];
+
+          if (!snapshotManager.values.has(uniqID)) {
+            // HMR-related
+            // Update the evaluated snapshots from JS.
+            createSnapshot(
+              uniqID,
+              evaluate<(ctx: SnapshotInstance) => FiberElement[]>(create),
+              update.map<(ctx: SnapshotInstance, index: number, oldValue: any) => void>(evaluate),
+              slot,
+              cssId,
+              entryName,
+            );
+          }
+        }
+        break;
+      }
+      case SnapshotOperation.DEV_ONLY_RegisterWorklet: {
+        // HMR-related
+        if (__DEV__) {
+          const hash: string = snapshotPatch[++i];
+          const fnStr: string = snapshotPatch[++i];
+          const fn = evaluate<(ctx: SnapshotInstance) => FiberElement[]>(fnStr);
+          registerWorklet('main-thread', hash, fn);
+        }
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Given an expression string, return the evaluated result with ReactLynx runtime injected.
+ *
+ * @param code - The code to be evaluated
+ * @returns the evaluated expression
+ */
+function evaluate<T>(code: string): T {
+  return new Function(`return ${code}`)();
+}

package/runtime/src/utils.ts

@@ -0,0 +1,35 @@
+// 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 function isDirectOrDeepEqual(a: any, b: any): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (
+    typeof a == 'object' && a !== null && typeof b == 'object' && b !== null && JSON.stringify(a) === JSON.stringify(b)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function isEmptyObject(obj?: object): obj is Record<string, never> {
+  for (var _ in obj) return false;
+  return true;
+}
+
+export function isSdkVersionGt(major: number, minor: number): boolean {
+  const lynxSdkVersion: string = SystemInfo.lynxSdkVersion || '1.0';
+  const version = lynxSdkVersion.split('.');
+  return Number(version[0]) > major || (Number(version[0]) == major && Number(version[1]) > minor);
+}
+
+export function pick<T extends object, K extends keyof T>(obj: T, keys: Iterable<K>): Pick<T, K> {
+  const result: any = {};
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}

package/runtime/src/worklet/ctx.ts

@@ -0,0 +1,22 @@
+// 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 type { Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { lynxWorkletJsImpl } from './jsImpl.js';
+
+/**
+ * @internal
+ */
+export function onPostWorkletCtx(afterValue: Worklet | null): Worklet | null {
+  const impl = lynxWorkletJsImpl();
+  if (!impl && afterValue) {
+    lynx.reportError(new Error('Main thread script requires Lynx sdk version 2.14'));
+    return null;
+  }
+  if (!afterValue) {
+    return afterValue;
+  }
+  impl?._workletExecIdMap?.add(afterValue);
+  return afterValue;
+}

package/runtime/src/worklet/execMap.ts

@@ -0,0 +1,50 @@
+// 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 type { JsFnHandle, Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { IndexMap } from './indexMap.js';
+
+/**
+ * `WorkletExecIdMap` ensures the worklet object is not released in js context when the main thread is still holding the
+ * worklet object (or any of its jsFnHandles). The worklet object holds the js functions which might be called by `runOnBackground()`.
+ * If the worklet object is incorrectly released earlier, the `runOnBackground()` would result in failure.
+ *
+ * Every time a worklet object is sent to the main thread, an `execId` is distributed and will be sent to element
+ * context with the worklet object. This relationship is recorded in this class. When all the references to the
+ * worklet object are released in the main thread, a message will be sent back to remove the record here.
+ *
+ * @internal
+ */
+export class WorkletExecIdMap extends IndexMap<Worklet> {
+  public override add(worklet: Worklet): number {
+    const execId = super.add(worklet);
+    worklet._execId = execId;
+    return execId;
+  }
+
+  public findJsFnHandle(execId: number, fnId: number): JsFnHandle | undefined {
+    const worklet = this.get(execId);
+    if (!worklet) {
+      return undefined;
+    }
+
+    const f = (obj: any): JsFnHandle | undefined => {
+      if (obj === null || typeof obj !== 'object') {
+        return undefined;
+      }
+      if ('_jsFnId' in obj && obj._jsFnId === fnId) {
+        return obj as JsFnHandle;
+      }
+      for (const i in obj) {
+        const result = f(obj[i]);
+        if (result) {
+          return result;
+        }
+      }
+      return undefined;
+    };
+
+    return f(worklet);
+  }
+}

package/runtime/src/worklet/functionality.ts

@@ -0,0 +1,12 @@
+// 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 { isSdkVersionGt } from '../utils.js';
+
+/**
+ * @internal
+ */
+export function enableRunOnBackground(): boolean {
+  return isSdkVersionGt(2, 15);
+}

package/runtime/src/worklet/hmr.ts

@@ -0,0 +1,26 @@
+// 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 { SnapshotOperation, __globalSnapshotPatch } from '../snapshotPatch.js';
+
+const workletHashSet: Set<string> = /* @__PURE__ */ new Set();
+
+/**
+ * @internal
+ */
+function registerWorkletOnBackground(_type: string, hash: string, fn: Function) {
+  if (workletHashSet.has(hash)) {
+    return;
+  }
+  workletHashSet.add(hash);
+  if (__globalSnapshotPatch) {
+    __globalSnapshotPatch.push(
+      SnapshotOperation.DEV_ONLY_RegisterWorklet,
+      hash,
+      // We use `Function.prototype.toString` to serialize the function for Lepus.
+      fn.toString(),
+    );
+  }
+}
+
+export { registerWorkletOnBackground };

package/runtime/src/worklet/indexMap.ts

@@ -0,0 +1,20 @@
+class IndexMap<T> {
+  protected lastIndex = 0;
+  protected indexMap: Map<number, T> = new Map();
+
+  public add(value: T): number {
+    const index = ++this.lastIndex;
+    this.indexMap.set(index, value);
+    return index;
+  }
+
+  public get(index: number): T | undefined {
+    return this.indexMap.get(index);
+  }
+
+  public remove(index: number): void {
+    this.indexMap.delete(index);
+  }
+}
+
+export { IndexMap };

package/runtime/src/worklet/jsImpl.ts

@@ -0,0 +1,86 @@
+// 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 { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { WorkletExecIdMap } from './execMap.js';
+import { enableRunOnBackground } from './functionality.js';
+
+interface LynxWorkletJsImpl {
+  _workletExecIdMap?: WorkletExecIdMap;
+  _workletJsFnLastId: number;
+  _workletRefLastId: number;
+  _workletRefInitValueSet: Set<number>;
+  _workletRefInitValuePatch: [number, unknown][];
+}
+
+/**
+ * @internal
+ */
+export function runJSFunction(event: RuntimeProxy.Event): void {
+  const impl = lynxWorkletJsImpl();
+  if (!impl || !impl._workletExecIdMap) {
+    return;
+  }
+  const data = JSON.parse(event.data);
+  const obj = impl._workletExecIdMap.findJsFnHandle(data.obj._execId, data.obj._jsFnId);
+  const f = obj?._fn;
+  if (!f) {
+    throw new Error('runOnBackground: JS function not found: ' + JSON.stringify(data.obj));
+  }
+  f(...data.params);
+}
+
+/**
+ * @internal
+ */
+export function removeJsWorklets(event: RuntimeProxy.Event): void {
+  const impl = lynxWorkletJsImpl();
+  if (!impl?._workletExecIdMap) {
+    return;
+  }
+  for (const id of event.data) {
+    impl._workletExecIdMap.remove(id);
+  }
+}
+
+function initWorklet(): boolean {
+  if (lynx.getCoreContext === undefined) {
+    return false;
+  }
+
+  lynx.lynxWorkletJsImpl = {
+    _workletJsFnLastId: 0,
+    _workletRefLastId: 0,
+    _workletRefInitValueSet: new Set<number>(),
+    _workletRefInitValuePatch: [],
+  };
+
+  if (enableRunOnBackground()) {
+    lynx.lynxWorkletJsImpl._workletExecIdMap = new WorkletExecIdMap();
+    lynx.getCoreContext().addEventListener(WorkletEvents.runOnBackground, runJSFunction);
+    lynx.getCoreContext().addEventListener(WorkletEvents.releaseBackgroundWorkletCtx, removeJsWorklets);
+  }
+
+  return true;
+}
+
+export function destroyWorklet(): void {
+  if (!lynx.lynxWorkletJsImpl) {
+    return;
+  }
+
+  lynx.lynxWorkletJsImpl = undefined;
+
+  if (enableRunOnBackground()) {
+    lynx.getCoreContext?.().removeEventListener(WorkletEvents.runOnBackground, runJSFunction);
+    lynx.getCoreContext?.().removeEventListener(WorkletEvents.releaseBackgroundWorkletCtx, removeJsWorklets);
+  }
+}
+
+export function lynxWorkletJsImpl(shouldInit: boolean = true): LynxWorkletJsImpl | undefined {
+  if (lynx.lynxWorkletJsImpl || (shouldInit && initWorklet())) {
+    return lynx.lynxWorkletJsImpl;
+  }
+  return undefined;
+}

package/runtime/src/worklet/runWorklet.ts

@@ -0,0 +1,88 @@
+// 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 type { JsFnHandle, Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { onPostWorkletCtx } from './ctx.js';
+import { enableRunOnBackground } from './functionality.js';
+import { lynxWorkletJsImpl } from './jsImpl.js';
+/**
+ * transform args of `runOnJS()`.
+ *
+ * @internal
+ */
+export function transformToWorklet(obj: Function): JsFnHandle {
+  const impl = lynxWorkletJsImpl();
+  const id = impl ? ++impl._workletJsFnLastId : 0;
+  if (typeof obj !== 'function') {
+    // We save the error message in the object, so that we can throw it later when the function is called on the main thread.
+    return {
+      _jsFnId: id,
+      _error: `Argument of runOnBackground should be a function, but got [${typeof obj}] instead`,
+    };
+  }
+  return {
+    _jsFnId: id,
+    _fn: obj,
+  };
+}
+
+/**
+ * `runOnMainThread` allows triggering main thread functions on the main thread asynchronously.
+ * @param fn - The main thread functions to be called.
+ * @returns A function. Calling which with the arguments to be passed to the main thread function to trigger it on the main thread.
+ * @public
+ */
+export function runOnMainThread<Fn extends (...args: any[]) => any>(fn: Fn): (...args: Parameters<Fn>) => void {
+  if (__LEPUS__) {
+    throw new Error('runOnMainThread can only be used on the background thread.');
+  }
+  const impl = lynxWorkletJsImpl();
+  if (!impl) {
+    throw new Error('runOnMainThread requires Lynx sdk version 2.14.');
+  }
+  return (...params: any[]): void => {
+    onPostWorkletCtx(fn as any as Worklet);
+    lynx.getCoreContext!().dispatchEvent({
+      type: WorkletEvents.runWorkletCtx,
+      data: JSON.stringify({
+        worklet: fn,
+        params,
+      }),
+    });
+  };
+}
+
+/**
+ * `runOnBackground` allows triggering js functions on the js context asynchronously.
+ * @param f - The js function to be called.
+ * @returns A function. Calling which with the arguments to be passed to the js function to trigger it on the js context.
+ * @public
+ */
+export function runOnBackground<Fn extends (...args: any[]) => any>(f: Fn): (...args: Parameters<Fn>) => void {
+  if (!enableRunOnBackground()) {
+    throw new Error('runOnBackground requires Lynx sdk version 2.16.');
+  }
+  if (__JS__) {
+    throw new Error('runOnBackground can not be used on the main thread.');
+  }
+  const obj = f as any as JsFnHandle;
+  if (obj._error) {
+    throw new Error(obj._error);
+  }
+  return (...params: any[]): void => {
+    if (lynx.getJSContext) {
+      lynx.getJSContext().dispatchEvent({
+        type: WorkletEvents.runOnBackground,
+        data: JSON.stringify({
+          obj: {
+            _jsFnId: obj._jsFnId,
+            _execId: obj._execId!,
+          },
+          params,
+        }),
+      });
+    }
+  };
+}

package/runtime/src/worklet/workletRef.ts

@@ -0,0 +1,229 @@
+// 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 type { RefObject } from 'react';
+
+import type { WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bindings';
+import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { lynxWorkletJsImpl } from './jsImpl.js';
+import { addWorkletRefInitValue } from './workletRefPool.js';
+import { useMemo } from '../hooks/react.js';
+
+abstract class WorkletRef<T> {
+  /**
+   * @internal
+   */
+  protected _id: number;
+  /**
+   * @internal
+   */
+  protected _initValue: T | undefined;
+  /**
+   * @internal
+   */
+  protected _type: string;
+  /**
+   * @internal
+   */
+  protected _lifecycleObserver: unknown;
+
+  /**
+   * @internal
+   */
+  protected constructor(initValue: T, type: string) {
+    if (__JS__) {
+      const impl = lynxWorkletJsImpl();
+      this._id = impl ? ++impl._workletRefLastId : 0;
+      this._initValue = initValue;
+      this._type = type;
+      addWorkletRefInitValue(this._id, initValue);
+    } else {
+      // Out of the js thread, the `WorkletRef` class here is just a placeholder and should not be accessed directly.
+      // The real WorkletRef will be generated by the worklet runtime.
+      this._id = -1;
+      this._type = '__LEPUS__';
+    }
+  }
+
+  get current(): T {
+    if (__JS__ && __DEV__) {
+      throw new Error('MainThreadRef: value of a MainThreadRef cannot be accessed in the background thread.');
+    }
+    if (__LEPUS__ && __DEV__) {
+      /* v8 ignore next */
+      throw new Error('MainThreadRef: value of a MainThreadRef cannot be accessed outside of main thread script.');
+    }
+    /* v8 ignore next */
+    return undefined as T;
+  }
+
+  set current(_: T) {
+    if (__JS__ && __DEV__) {
+      throw new Error('MainThreadRef: value of a MainThreadRef cannot be accessed in the background thread.');
+    }
+    if (__LEPUS__ && __DEV__) {
+      throw new Error('MainThreadRef: value of a MainThreadRef cannot be accessed outside of main thread script.');
+    }
+  }
+
+  /**
+   * @internal
+   */
+  toJSON(): { _wvid: WorkletRefImpl<T>['_wvid'] } {
+    return {
+      _wvid: this._id,
+    };
+  }
+}
+
+/**
+ * A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
+ * states between main thread function calls.
+ * The data saved in `current` property of the `MainThreadRef` can be read and written in
+ * multiple main thread functions.
+ * @public
+ */
+export class MainThreadRef<T> extends WorkletRef<T> {
+  constructor(initValue: T) {
+    super(initValue, 'main-thread');
+    if (__JS__) {
+      const id = this._id;
+      this._lifecycleObserver = lynx.getNativeApp().createJSObjectDestructionObserver(() => {
+        lynx.getCoreContext?.().dispatchEvent({
+          type: WorkletEvents.releaseWorkletRef,
+          data: {
+            id,
+          },
+        });
+      });
+    }
+  }
+}
+
+/**
+ * Create A `MainThreadRef`.
+ *
+ * A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
+ * states between main thread function calls.
+ * The data saved in `current` property of the `MainThreadRef` can be read and written in
+ * multiple main thread functions.
+ *
+ * It is a hook and it should only be called at the top level of your component.
+ *
+ * @param initValue - The init value of the `MainThreadRef`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { useMainThreadRef } from '@lynx-js/react'
+ * import type { MainThread } from '@lynx-js/types'
+ *
+ * export function App() {
+ *   const ref = useMainThreadRef<MainThread.Element>(null)
+ *
+ *   const handleTap = () => {
+ *     'main thread'
+ *     ref.current?.setStyleProperty('background-color', 'blue')
+ *   }
+ *
+ *   return (
+ *     <view
+ *       main-thread:ref={ref}
+ *       main-thread:bindtap={handleTap}
+ *       style={{ width: '300px', height: '300px' }}
+ *     />
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useMainThreadRef<T>(initValue: T): MainThreadRef<T>;
+
+// convenience overload for refs given as a ref prop as they typically start with a null value
+/**
+ * Create A `MainThreadRef`.
+ *
+ * A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
+ * states between main thread function calls.
+ * The data saved in `current` property of the `MainThreadRef` can be read and written in
+ * multiple main thread functions.
+ *
+ * It is a hook and it should only be called at the top level of your component.
+ *
+ * @param initValue - The init value of the `MainThreadRef`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { useMainThreadRef } from '@lynx-js/react'
+ * import type { MainThread } from '@lynx-js/types'
+ *
+ * export function App() {
+ *   const ref = useMainThreadRef<MainThread.Element>(null)
+ *
+ *   const handleTap = () => {
+ *     'main thread'
+ *     ref.current?.setStyleProperty('background-color', 'blue')
+ *   }
+ *
+ *   return (
+ *     <view
+ *       main-thread:ref={ref}
+ *       main-thread:bindtap={handleTap}
+ *       style={{ width: '300px', height: '300px' }}
+ *     />
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useMainThreadRef<T>(initValue: T | null): RefObject<T>;
+
+// convenience overload for potentially undefined initialValue / call with 0 arguments
+// has a default to stop it from defaulting to {} instead
+/**
+ * Create A `MainThreadRef`.
+ *
+ * A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
+ * states between main thread function calls.
+ * The data saved in `current` property of the `MainThreadRef` can be read and written in
+ * multiple main thread functions.
+ *
+ * It is a hook and it should only be called at the top level of your component.
+ *
+ * @example
+ *
+ * ```ts
+ * import { useMainThreadRef } from '@lynx-js/react'
+ * import type { MainThread } from '@lynx-js/types'
+ *
+ * export function App() {
+ *   const ref = useMainThreadRef<MainThread.Element>(null)
+ *
+ *   const handleTap = () => {
+ *     'main thread'
+ *     ref.current?.setStyleProperty('background-color', 'blue')
+ *   }
+ *
+ *   return (
+ *     <view
+ *       main-thread:ref={ref}
+ *       main-thread:bindtap={handleTap}
+ *       style={{ width: '300px', height: '300px' }}
+ *     />
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useMainThreadRef<T = undefined>(): MainThreadRef<T | undefined>;
+
+export function useMainThreadRef<T>(initValue?: T): MainThreadRef<T | undefined> {
+  return useMemo(() => {
+    return new MainThreadRef(initValue);
+  }, []);
+}