@lynx-js/react 0.110.1 → 0.111.0

package/runtime/src/backgroundSnapshot.ts

@@ -35,8 +35,7 @@ import { onPostWorkletCtx } from './worklet/ctx.js';
 export class BackgroundSnapshotInstance {
   constructor(public type: string) {
     this.__snapshot_def = snapshotManager.values.get(type)!;
-    let id;
-    id = this.__id = backgroundSnapshotInstanceManager.nextId += 1;
+    const id = this.__id = backgroundSnapshotInstanceManager.nextId += 1;
     backgroundSnapshotInstanceManager.values.set(id, this);
 
     __globalSnapshotPatch?.push(SnapshotOperation.CreateElement, type, id);
@@ -45,6 +44,7 @@ export class BackgroundSnapshotInstance {
   __id: number;
   __values: any[] | undefined;
   __snapshot_def: Snapshot;
+  __extraProps?: Record<string, unknown> | undefined;
 
   private __parent: BackgroundSnapshotInstance | null = null;
   private __firstChild: BackgroundSnapshotInstance | null = null;
@@ -191,7 +191,7 @@ export class BackgroundSnapshotInstance {
     return nodes;
   }
 
-  setAttribute(key: string | number, value: any): void {
+  setAttribute(key: string | number, value: unknown): void {
     if (__PROFILE__) {
       console.profile('setAttribute');
     }
@@ -199,8 +199,12 @@ export class BackgroundSnapshotInstance {
       if (__globalSnapshotPatch) {
         const oldValues = this.__values;
         if (oldValues) {
-          for (let index = 0; index < value.length; index++) {
-            const { needUpdate, valueToCommit } = this.setAttributeImpl(value[index], oldValues[index], index);
+          for (let index = 0; index < (value as unknown[]).length; index++) {
+            const { needUpdate, valueToCommit } = this.setAttributeImpl(
+              (value as unknown[])[index],
+              oldValues[index],
+              index,
+            );
             if (needUpdate) {
               __globalSnapshotPatch.push(
                 SnapshotOperation.SetAttribute,
@@ -212,9 +216,9 @@ export class BackgroundSnapshotInstance {
           }
         } else {
           const patch = [];
-          const length = value.length;
+          const length = (value as unknown[]).length;
           for (let index = 0; index < length; ++index) {
-            const { valueToCommit } = this.setAttributeImpl(value[index], null, index);
+            const { valueToCommit } = this.setAttributeImpl((value as unknown[])[index], null, index);
             patch[index] = valueToCommit;
           }
           __globalSnapshotPatch.push(
@@ -235,22 +239,24 @@ export class BackgroundSnapshotInstance {
           }
         });
       }
-      this.__values = value;
+      this.__values = value as unknown[];
       if (__PROFILE__) {
         console.profileEnd();
       }
       return;
     }
 
-    // old path (`<__snapshot_xxxx_xxxx __0={} __1={} />` or `this.setAttribute(0, xxx)`)
-    // is reserved as slow path
-    const index = typeof key === 'string' ? Number(key.slice(2)) : key;
-    (this.__values ??= [])[index] = value;
-
+    if (typeof key === 'string') {
+      (this.__extraProps ??= {})[key] = value;
+    } else {
+      // old path (`this.setAttribute(0, xxx)`)
+      // is reserved as slow path
+      (this.__values ??= [])[key] = value;
+    }
     __globalSnapshotPatch?.push(
       SnapshotOperation.SetAttribute,
       this.__id,
-      index,
+      key,
       value,
     );
     if (__PROFILE__) {
@@ -341,7 +347,7 @@ export function hydrate(
 ): SnapshotPatch {
   initGlobalSnapshotPatch();
 
-  const helper2 = (afters: BackgroundSnapshotInstance[], parentId: number) => {
+  const helper2 = (afters: BackgroundSnapshotInstance[], parentId: number, targetId?: number) => {
     for (const child of afters) {
       const id = child.__id;
       __globalSnapshotPatch!.push(SnapshotOperation.CreateElement, child.type, id);
@@ -350,8 +356,12 @@ export function hydrate(
         child.__values = undefined;
         child.setAttribute('values', values);
       }
+      const extraProps = child.__extraProps;
+      for (const key in extraProps) {
+        child.setAttribute(key, extraProps[key]);
+      }
       helper2(child.childNodes, id);
-      __globalSnapshotPatch!.push(SnapshotOperation.InsertBefore, parentId, id, undefined);
+      __globalSnapshotPatch!.push(SnapshotOperation.InsertBefore, parentId, id, targetId);
     }
   };
 
@@ -361,35 +371,45 @@ export function hydrate(
   ) => {
     hydrationMap.set(after.__id, before.id);
     backgroundSnapshotInstanceManager.updateId(after.__id, before.id);
-    after.__values?.forEach((value, index) => {
-      const old = before.values![index];
+    after.__values?.forEach((value: unknown, index) => {
+      const old: unknown = before.values![index];
 
       if (value) {
-        if (value.__spread) {
-          // `value.__spread` my contain event ids using snapshot ids before hydration. Remove it.
-          delete value.__spread;
-          value = transformSpread(after, index, value);
-          for (const key in value) {
-            if (value[key] && value[key]._wkltId) {
-              onPostWorkletCtx(value[key]);
-            } else if (value[key] && value[key].__isGesture) {
-              processGestureBackground(value[key] as GestureKind);
+        if (typeof value === 'object') {
+          if ('__spread' in value) {
+            // `value.__spread` my contain event ids using snapshot ids before hydration. Remove it.
+            delete value.__spread;
+            const __spread = transformSpread(after, index, value);
+            for (const key in __spread) {
+              const v = __spread[key];
+              if (v && typeof v === 'object') {
+                if ('_wkltId' in v) {
+                  onPostWorkletCtx(v as Worklet);
+                } else if ('__isGesture' in v) {
+                  processGestureBackground(v as GestureKind);
+                }
+              }
             }
+            (after.__values![index]! as Record<string, unknown>)['__spread'] = __spread;
+            value = __spread;
+          } else if ('__ref' in value) {
+            // skip patch
+            value = old;
+          } else if ('_wkltId' in value) {
+            onPostWorkletCtx(value as Worklet);
+          } else if ('__isGesture' in value) {
+            processGestureBackground(value as GestureKind);
           }
-          after.__values![index]!.__spread = value;
-        } else if (value.__ref) {
-          // skip patch
-          value = old;
         } else if (typeof value === 'function') {
-          value = `${after.__id}:${index}:`;
+          if ('__ref' in value) {
+            // skip patch
+            value = old;
+          } else {
+            value = `${after.__id}:${index}:`;
+          }
         }
       }
 
-      if (value && value._wkltId) {
-        onPostWorkletCtx(value);
-      } else if (value && value.__isGesture) {
-        processGestureBackground(value);
-      }
       if (!isDirectOrDeepEqual(value, old)) {
         __globalSnapshotPatch!.push(
           SnapshotOperation.SetAttribute,
@@ -400,9 +420,24 @@ export function hydrate(
       }
     });
 
+    if (after.__extraProps) {
+      for (const key in after.__extraProps) {
+        const value = after.__extraProps[key];
+        const old = before.extraProps?.[key];
+        if (!isDirectOrDeepEqual(value, old)) {
+          __globalSnapshotPatch!.push(
+            SnapshotOperation.SetAttribute,
+            after.__id,
+            key,
+            value,
+          );
+        }
+      }
+    }
+
     const { slot } = after.__snapshot_def;
 
-    const beforeChildNodes = before.children || [];
+    const beforeChildNodes = before.children ?? [];
     const afterChildNodes = after.childNodes;
 
     if (!slot) {
@@ -433,23 +468,7 @@ export function hydrate(
             beforeChildNodes,
             diffResult,
             (node, target) => {
-              __globalSnapshotPatch!.push(
-                SnapshotOperation.CreateElement,
-                node.type,
-                node.__id,
-              );
-              helper2(node.childNodes, node.__id);
-              const values = node.__values;
-              if (values) {
-                node.__values = undefined;
-                node.setAttribute('values', values);
-              }
-              __globalSnapshotPatch!.push(
-                SnapshotOperation.InsertBefore,
-                before.id,
-                node.__id,
-                target?.id,
-              );
+              helper2([node], before.id, target?.id);
               return undefined as unknown as SerializedSnapshotInstance;
             },
             node => {

package/runtime/src/compat/initData.ts

@@ -5,6 +5,7 @@ import type { ComponentChildren, Consumer, Context, Provider } from 'preact';
 import type { ComponentClass } from 'react';
 
 import { useLynxGlobalEventListener } from '../hooks/useLynxGlobalEventListener.js';
+import { globalFlushOptions } from '../lifecycle/patch/commit.js';
 
 type Getter<T> = {
   [key in keyof T]: () => T[key];
@@ -33,6 +34,9 @@ export function factory<Data>(
     const [__, set] = useState<Data>(lynx[prop] as Data);
 
     const handleChange = () => {
+      if (prop === '__initData') {
+        globalFlushOptions.triggerDataUpdated = true;
+      }
       set(lynx[prop] as Data);
     };
 
@@ -52,6 +56,9 @@ export function factory<Data>(
   const use = (): Data => {
     const [__, set] = useState(lynx[prop]);
     useChanged(() => {
+      if (prop === '__initData') {
+        globalFlushOptions.triggerDataUpdated = true;
+      }
       set(lynx[prop]);
     });
 
@@ -65,6 +72,7 @@ export function factory<Data>(
   };
 
   return {
+    /* v8 ignore next */
     Context: () => Context,
     Provider: () => Provider,
     Consumer: () => Consumer,
@@ -100,6 +108,7 @@ export function factory<Data>(
  */
 export function withInitDataInState<P, S>(App: ComponentClass<P, S>): ComponentClass<P, S> {
   const isClassComponent = 'prototype' in App && 'render' in App.prototype;
+  /* v8 ignore next 4 */
   if (!isClassComponent) {
     // return as-is when not class component
     return App;
@@ -119,6 +128,7 @@ export function withInitDataInState<P, S>(App: ComponentClass<P, S>): ComponentC
         lynx.getJSModule('GlobalEventEmitter').addListener(
           'onDataChanged',
           this.h = () => {
+            globalFlushOptions.triggerDataUpdated = true;
             this.setState(lynx.__initData as S);
           },
         );

package/runtime/src/index.ts

@@ -11,6 +11,7 @@ import {
   PureComponent,
   Suspense,
   lazy as backgroundLazy,
+  cloneElement,
   createContext,
   createElement,
   createRef,
@@ -86,6 +87,7 @@ export {
   Suspense,
   lazy,
   createElement,
+  cloneElement,
   useSyncExternalStore,
 };
 

package/runtime/src/lifecycle/patch/commit.ts

@@ -23,13 +23,7 @@ import type { VNode } from 'preact';
 import { options } from 'preact';
 
 import { LifecycleConstant } from '../../lifecycleConstant.js';
-import {
-  PerformanceTimingKeys,
-  globalPipelineOptions,
-  markTiming,
-  markTimingLegacy,
-  setPipeline,
-} from '../../lynx/performance.js';
+import { globalPipelineOptions, markTiming, markTimingLegacy, setPipeline } from '../../lynx/performance.js';
 import { COMMIT } from '../../renderToOpcodes/constants.js';
 import { applyQueuedRefs } from '../../snapshot/ref.js';
 import { backgroundSnapshotInstanceManager } from '../../snapshot.js';
@@ -88,8 +82,8 @@ function replaceCommitHook(): void {
     }
 
     // Mark the end of virtual DOM diffing phase for performance tracking
-    markTimingLegacy(PerformanceTimingKeys.updateDiffVdomEnd);
-    markTiming(PerformanceTimingKeys.diffVdomEnd);
+    markTimingLegacy('updateDiffVdomEnd');
+    markTiming('diffVdomEnd');
 
     const backgroundSnapshotInstancesToRemove = globalBackgroundSnapshotInstancesToRemove;
     globalBackgroundSnapshotInstancesToRemove = [];
@@ -167,7 +161,7 @@ function commitPatchUpdate(patchList: PatchList, patchOptions: Omit<PatchOptions
   if (__PROFILE__) {
     console.profile('commitChanges');
   }
-  markTiming(PerformanceTimingKeys.packChangesStart);
+  markTiming('packChangesStart');
   const obj: {
     data: string;
     patchOptions: PatchOptions;
@@ -178,7 +172,7 @@ function commitPatchUpdate(patchList: PatchList, patchOptions: Omit<PatchOptions
       reloadVersion: getReloadVersion(),
     },
   };
-  markTiming(PerformanceTimingKeys.packChangesEnd);
+  markTiming('packChangesEnd');
   if (globalPipelineOptions) {
     obj.patchOptions.pipelineOptions = globalPipelineOptions;
     setPipeline(undefined);

package/runtime/src/lifecycle/patch/snapshotPatch.ts

@@ -8,16 +8,16 @@
  * efficient transmission between threads and application to element tree.
  */
 
-export const enum SnapshotOperation {
-  CreateElement,
-  InsertBefore,
-  RemoveChild,
-  SetAttribute,
-  SetAttributes,
+export const SnapshotOperation = {
+  CreateElement: 0,
+  InsertBefore: 1,
+  RemoveChild: 2,
+  SetAttribute: 3,
+  SetAttributes: 4,
 
-  DEV_ONLY_AddSnapshot = 100,
-  DEV_ONLY_RegisterWorklet = 101,
-}
+  DEV_ONLY_AddSnapshot: 100,
+  DEV_ONLY_RegisterWorklet: 101,
+} as const;
 
 // Operation format definitions:
 //

package/runtime/src/lifecycle/patch/updateMainThread.ts

@@ -8,7 +8,7 @@ import type { PatchList, PatchOptions } from './commit.js';
 import { setMainThreadHydrationFinished } from './isMainThreadHydrationFinished.js';
 import { snapshotPatchApply } from './snapshotPatchApply.js';
 import { LifecycleConstant } from '../../lifecycleConstant.js';
-import { PerformanceTimingKeys, markTiming, setPipeline } from '../../lynx/performance.js';
+import { markTiming, setPipeline } from '../../lynx/performance.js';
 import { __pendingListUpdates } from '../../pendingListUpdates.js';
 import { applyRefQueue } from '../../snapshot/workletRef.js';
 import { __page } from '../../snapshot.js';
@@ -25,12 +25,12 @@ function updateMainThread(
   }
 
   setPipeline(patchOptions.pipelineOptions);
-  markTiming(PerformanceTimingKeys.mtsRenderStart);
-  markTiming(PerformanceTimingKeys.parseChangesStart);
+  markTiming('mtsRenderStart');
+  markTiming('parseChangesStart');
   const { patchList, flushOptions = {} } = JSON.parse(data) as PatchList;
 
-  markTiming(PerformanceTimingKeys.parseChangesEnd);
-  markTiming(PerformanceTimingKeys.patchChangesStart);
+  markTiming('parseChangesEnd');
+  markTiming('patchChangesStart');
 
   for (const { snapshotPatch, workletRefInitValuePatch } of patchList) {
     updateWorkletRefInitValueChanges(workletRefInitValuePatch);
@@ -42,8 +42,8 @@ function updateMainThread(
     // console.debug('********** Lepus updatePatch:');
     // printSnapshotInstance(snapshotInstanceManager.values.get(-1)!);
   }
-  markTiming(PerformanceTimingKeys.patchChangesEnd);
-  markTiming(PerformanceTimingKeys.mtsRenderEnd);
+  markTiming('patchChangesEnd');
+  markTiming('mtsRenderEnd');
   if (patchOptions.isHydration) {
     setMainThreadHydrationFinished(true);
   }
@@ -51,7 +51,6 @@ function updateMainThread(
   if (patchOptions.pipelineOptions) {
     flushOptions.pipelineOptions = patchOptions.pipelineOptions;
   }
-  // TODO: triggerDataUpdated?
   __FlushElementTree(__page, flushOptions);
 }
 

package/runtime/src/lifecycleConstant.ts

@@ -7,6 +7,7 @@ export const enum LifecycleConstant {
   globalEventFromLepus = 'globalEventFromLepus',
   jsReady = 'rLynxJSReady',
   patchUpdate = 'rLynxChange',
+  publishEvent = 'rLynxPublishEvent',
 }
 
 export interface FirstScreenData {

package/runtime/src/list.ts

@@ -1,12 +1,15 @@
 // 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 { LifecycleConstant } from './lifecycleConstant.js';
 import { applyRefQueue } from './snapshot/workletRef.js';
 import type { SnapshotInstance } from './snapshot.js';
+import { maybePromise } from './utils.js';
 
 export const gSignMap: Record<number, Map<number, SnapshotInstance>> = {};
 export const gRecycleMap: Record<number, Map<string, Map<number, SnapshotInstance>>> = {};
 const gParentWeakMap: WeakMap<SnapshotInstance, unknown> = new WeakMap();
+const resolvedPromise = /* @__PURE__ */ Promise.resolve();
 
 export function clearListGlobal(): void {
   for (const key in gSignMap) {
@@ -38,10 +41,10 @@ export function componentAtIndexFactory(
     }
   });
 
-  const componentAtIndex = (
+  const componentAtChildCtx = (
     list: FiberElement,
     listID: number,
-    cellIndex: number,
+    childCtx: SnapshotInstance,
     operationID: number,
     enableReuseNotification: boolean,
     enableBatchRender: boolean = false,
@@ -53,13 +56,55 @@ export function componentAtIndexFactory(
       throw new Error('componentAtIndex called on removed list');
     }
 
-    const childCtx = ctx[cellIndex];
-    if (!childCtx) {
-      throw new Error('childCtx not found');
-    }
-
     const platformInfo = childCtx.__listItemPlatformInfo ?? {};
 
+    // The lifecycle of this `__extraProps.isReady`:
+    //   0 -> Promise<number> -> 1
+    // 0: The initial state, the list-item is not ready yet, we will send a event to background
+    //    when `componentAtIndex` is called on it
+    // Promise<number>: A promise that will be resolved when the list-item is ready
+    // 1: The list-item is ready, we can use it to render the list
+    if (childCtx.__extraProps?.['isReady'] === 0) {
+      if (
+        typeof __GetAttributeByName === 'function'
+        && __GetAttributeByName(list, 'custom-list-name') === 'list-container'
+      ) {
+        // we are in supported env
+        // do not throw
+      } else {
+        throw new Error(
+          'Unsupported: `<list-item/>` with `defer={true}` must be used with `<list custom-list-name="list-container"/>`',
+        );
+      }
+
+      __OnLifecycleEvent([LifecycleConstant.publishEvent, {
+        handlerName: `${childCtx.__id}:__extraProps:onComponentAtIndex`,
+        data: {},
+      }]);
+
+      let p: Promise<number>;
+      return (p = new Promise<number>((resolve) => {
+        Object.defineProperty(childCtx.__extraProps, 'isReady', {
+          set(isReady) {
+            if (isReady === 1) {
+              delete childCtx.__extraProps!['isReady'];
+              childCtx.__extraProps!['isReady'] = 1;
+
+              void resolvedPromise.then(() => {
+                // the cellIndex may be changed already, but the `childCtx` is the same
+                resolve(componentAtChildCtx(list, listID, childCtx, operationID, enableReuseNotification));
+              });
+            }
+          },
+          get() {
+            return p;
+          },
+        });
+      }));
+    } else if (maybePromise<number>(childCtx.__extraProps?.['isReady'])) {
+      throw new Error('componentAtIndex was called on a pending deferred list item');
+    }
+
     const uniqID = childCtx.type + (platformInfo['reuse-identifier'] ?? '');
     const recycleSignMap = recycleMap.get(uniqID);
 
@@ -102,6 +147,11 @@ export function componentAtIndexFactory(
       oldCtx.unRenderElements();
       if (!oldCtx.__id) {
         oldCtx.tearDown();
+      } else if (oldCtx.__extraProps?.['isReady'] === 1) {
+        __OnLifecycleEvent([LifecycleConstant.publishEvent, {
+          handlerName: `${oldCtx.__id}:__extraProps:onRecycleComponent`,
+          data: {},
+        }]);
       }
       const root = childCtx.__element_root!;
       applyRefQueue();
@@ -156,25 +206,78 @@ export function componentAtIndexFactory(
     return sign;
   };
 
-  const componentAtIndexes = (
+  function componentAtIndex(
+    list: FiberElement,
+    listID: number,
+    cellIndex: number,
+    operationID: number,
+    enableReuseNotification: boolean,
+  ) {
+    const childCtx = ctx[cellIndex];
+    if (!childCtx) {
+      throw new Error('childCtx not found');
+    }
+    const r = componentAtChildCtx(list, listID, childCtx, operationID, enableReuseNotification);
+
+    /* v8 ignore start */
+    if (process.env['NODE_ENV'] === 'test') {
+      return r;
+    } else {
+      return typeof r === 'number' ? r : undefined;
+    }
+    /* v8 ignore end */
+  }
+
+  function componentAtIndexes(
     list: FiberElement,
     listID: number,
     cellIndexes: number[],
     operationIDs: number[],
     enableReuseNotification: boolean,
     asyncFlush: boolean,
-  ) => {
-    const uiSigns = cellIndexes.map((cellIndex, index) => {
-      const operationID = operationIDs[index] ?? 0;
-      return componentAtIndex(list, listID, cellIndex, operationID, enableReuseNotification, true, asyncFlush);
+  ) {
+    let hasUnready = false;
+    const p: Array<Promise<number> | number> = [];
+
+    cellIndexes.forEach((cellIndex, index) => {
+      const operationID = operationIDs[index]!;
+      const childCtx = ctx[cellIndex];
+      if (!childCtx) {
+        throw new Error('childCtx not found');
+      }
+
+      const u = componentAtChildCtx(list, listID, childCtx, operationID, enableReuseNotification, true, asyncFlush);
+      if (typeof u === 'number') {
+        // ready
+      } else {
+        hasUnready = true;
+      }
+      p.push(u);
     });
+
+    // We need __FlushElementTree twice:
+    // 1. The first time is sync, we flush the items that are ready, with unready items' uiSign as -1.
+    // 2. The second time is async, with all the uiSigns.
+    // NOTE: The `operationIDs` passed to __FlushElementTree must be the one passed in,
+    // not the one generated by any code here, to workaround a bug of Lynx Engine.
+    // So we CANNOT split the `operationIDs` into two parts: one for ready items, one for unready items.
+    if (hasUnready) {
+      void Promise.all(p).then((uiSigns) => {
+        __FlushElementTree(list, {
+          triggerLayout: true,
+          operationIDs,
+          elementIDs: uiSigns,
+          listID,
+        });
+      });
+    }
     __FlushElementTree(list, {
       triggerLayout: true,
-      operationIDs: operationIDs,
-      elementIDs: uiSigns,
+      operationIDs,
+      elementIDs: cellIndexes.map((_, index) => typeof p[index] === 'number' ? p[index] : -1),
       listID,
     });
-  };
+  }
   return [componentAtIndex, componentAtIndexes] as const;
 }
 

package/runtime/src/lynx/calledByNative.ts

@@ -12,7 +12,7 @@ import { __root, setRoot } from '../root.js';
 import { applyRefQueue } from '../snapshot/workletRef.js';
 import { SnapshotInstance, __page, setupPage } from '../snapshot.js';
 import { isEmptyObject } from '../utils.js';
-import { PerformanceTimingKeys, markTiming, setPipeline } from './performance.js';
+import { markTiming, setPipeline } from './performance.js';
 
 function ssrEncode() {
   const { __opcodes } = __root;
@@ -116,13 +116,14 @@ function updatePage(data: Record<string, unknown> | undefined, options?: UpdateP
     Object.assign(lynx.__initData, data);
   }
 
+  const flushOptions = options ?? {};
   if (!isJSReady) {
     const oldRoot = __root;
     setRoot(new SnapshotInstance('root'));
     __root.__jsx = oldRoot.__jsx;
 
     setPipeline(options?.pipelineOptions);
-    markTiming(PerformanceTimingKeys.updateDiffVdomStart);
+    markTiming('updateDiffVdomStart');
     {
       __pendingListUpdates.clear();
       renderMainThread();
@@ -138,14 +139,11 @@ function updatePage(data: Record<string, unknown> | undefined, options?: UpdateP
       __pendingListUpdates.flush();
       applyRefQueue();
     }
-    markTiming(PerformanceTimingKeys.updateDiffVdomEnd);
+    flushOptions.triggerDataUpdated = true;
+    markTiming('updateDiffVdomEnd');
   }
 
-  if (options) {
-    __FlushElementTree(__page, options);
-  } else {
-    __FlushElementTree();
-  }
+  __FlushElementTree(__page, flushOptions);
 }
 
 function updateGlobalProps(_data: any, options?: UpdatePageOption): void {