@mantou/gem 2.2.13 → 2.2.15

package/src/lib/reactive.ts

@@ -1,11 +1,13 @@
 // biome-ignore-all lint/plugin/no_this_effect: 兼容生命周期
 
 import type * as Lit from './lit-html';
+import { isServer } from './server';
 import type { Store } from './store';
 import { connect } from './store';
 import {
   addListener,
   addMicrotask,
+  assignState,
   createUpdater,
   GemError,
   isArrayChange,
@@ -29,10 +31,18 @@ let hydrationEngine = (_value: unknown, _container: HTMLElement | DocumentFragme
   return;
 };
 
-export function setHydrationEngine(engine: typeof hydrationEngine) {
+// 在元素首次渲染前恢复 SSR 的状态
+let restoreState: ((ele: GemElement) => void) | undefined;
+
+export function setHydrationEngine(engine: typeof hydrationEngine, restore?: typeof restoreState) {
   hydrationEngine = engine;
+  restoreState = restore;
 }
 
+/** 渲染元素内容，SSR 时由水合引擎接管 */
+export const _renderRoot = (value: unknown, container: HTMLElement | DocumentFragment) =>
+  hydrationEngine(value, container) || render(value, container);
+
 const { assign, defineProperty } = Object;
 
 // https://github.com/tc39/proposal-decorator-metadata
@@ -40,8 +50,6 @@ defineProperty(Symbol, 'metadata', { value: Symbol.for('Symbol.metadata') });
 
 const execCallback = (fun: any) => typeof fun === 'function' && fun();
 
-const ssrNativeQueueMicrotask = (globalThis as any).nQM;
-
 // 读取构造样式表，跨多个 gem 工作
 export const SheetToken = Symbol.for('gem@sheetToken');
 export type SheetTokenType = typeof SheetToken;
@@ -186,7 +194,7 @@ const updateStyleSheets = (map: Map<CSSStyleSheet, number>, sheets: CSSStyleShee
   if (needUpdate) {
     // 避免重复更新，例如 list 元素增删，全 light dom 时 document 更新
     // 在 SSR 中应该区别 effect 强制执行
-    addMicrotask(rootUpdateFnMap.get(map)!, ssrNativeQueueMicrotask);
+    addMicrotask(rootUpdateFnMap.get(map)!);
   }
 };
 
@@ -286,10 +294,14 @@ const noBlockingTaskList = new LinkedList<() => void>();
 const tick = (timeStamp = performance.now()) => {
   if (performance.now() > timeStamp + 50) return requestAnimationFrame(tick);
   const task = noBlockingTaskList.get();
-  if (task) {
+  if (!task) return;
+  // 出错时继续执行后面的任务，否则剩下的任务不会再被调度
+  try {
     task();
-    tick(timeStamp);
+  } catch (err) {
+    reportError(err);
   }
+  tick(timeStamp);
 };
 noBlockingTaskList.addEventListener('start', () => addMicrotask(tick));
 
@@ -340,14 +352,14 @@ export abstract class GemElement extends HTMLElement {
         const effect = ele.#effectList.at(0);
         // https://github.com/mantou132/gem/issues/203
         // SSR 不会执行 initEffect，应该跳过
-        if (!ssrNativeQueueMicrotask && ele.#isMounted && effect && !effect.initialized) {
+        if (!isServer && ele.#isMounted && effect && !effect.initialized) {
           throw new GemError(`Don't set state sync before insert the DOM`);
         }
-        assign(state, payload);
+        assignState(state, payload);
         // 避免无限刷新
         // 挂载前 set state 不应该触发更新
         // SSR 中渲染 <gem-route>，其他情况的 SSR 应该也可以执行
-        if (!ele.#rendering && ele.#isMounted) addMicrotask(ele.#update, ssrNativeQueueMicrotask);
+        if (!ele.#rendering && ele.#isMounted) addMicrotask(ele.#update);
       });
       ele.#internals.stateList.push(state);
       return state;
@@ -429,11 +441,17 @@ export abstract class GemElement extends HTMLElement {
       const isLight = this.#renderRoot === this;
       const temp = item ? item.render() : isLight ? undefined : html`<slot></slot>`;
       if (temp === undefined) return;
-      const r = temp !== null ? temp : html`<style>${isLight ? '@scope' : ':host'}{&{display:none!important;}}</style>`;
-      hydrationEngine(r, this.#renderRoot) || render(r, this.#renderRoot);
+      // `<style>` 中不使用绑定，SSR 水合不支持
+      const r =
+        temp ??
+        (isLight
+          ? html`<style>@scope{&{display:none!important;}}</style>`
+          : html`<style>:host{&{display:none!important;}}</style>`);
+      _renderRoot(r, this.#renderRoot);
     } catch (err) {
-      this.dispatchEvent(new CustomEvent(_RenderErrorEvent, { bubbles: true, composed: true, detail: err }));
-      throw err;
+      const evt = new CustomEvent(_RenderErrorEvent, { bubbles: true, composed: true, cancelable: true, detail: err });
+      // `@fallback` 处理了错误
+      if (this.dispatchEvent(evt)) throw err;
     } finally {
       this.#rendering = false;
     }
@@ -447,12 +465,13 @@ export abstract class GemElement extends HTMLElement {
       (item || !this.#renderList.length)
     ) {
       this.#render(item);
-      addMicrotask(this.#execEffect);
+      if (!isServer) addMicrotask(this.#execEffect);
     }
   };
 
   #update = () => {
-    if (this.#metadata.noBlocking) {
+    // SSR 需要同步渲染
+    if (this.#metadata.noBlocking && !isServer) {
       noBlockingTaskList.add(this.#updateCallback);
     } else {
       this.#updateCallback();
@@ -506,7 +525,8 @@ export abstract class GemElement extends HTMLElement {
   };
 
   #disconnectStore?: (() => void)[];
-  #connectedCallback = async () => {
+  // 同步执行，SSR 需要捕获渲染错误
+  #connectedCallback = () => {
     if (this.#isAppendReason) {
       this.#isAppendReason = false;
       // https://github.com/mantou132/gem/issues/202
@@ -526,12 +546,14 @@ export abstract class GemElement extends HTMLElement {
     if (!mode && this.#renderList.length && !penetrable) this.#internals.states.add(BoundaryCSSState);
 
     this.#disconnectStore = observedStores?.map((store) => connect(store, this.#update));
+    restoreState?.(this);
     this.#render(this.#renderItem);
     this.#isMounted = true;
     this.#clearStyle = this.#prepareStyle();
     // 等待所有元素的样式被应用，再执行回调
     // 这让 mounted 和 effect 回调和其他回调一样保持一样的异步行为
-    addMicrotask(this.#initEffect);
+    // SSR 不执行副作用
+    if (!isServer) addMicrotask(this.#initEffect);
   };
 
   /**
@@ -540,7 +562,7 @@ export abstract class GemElement extends HTMLElement {
    * use `@mounted`
    */
   connectedCallback(): Unique {
-    if (this.#metadata.noBlocking) {
+    if (this.#metadata.noBlocking && !isServer) {
       noBlockingTaskList.add(this.#connectedCallback);
     } else {
       this.#connectedCallback();

package/src/lib/server.ts

@@ -0,0 +1,45 @@
+// SSR 相关的功能都在这里
+//
+// `@mantou/gem-ssr` 在加载 Gem 前提供 `__GEM_SSR__`，返回当前请求的作用域，
+// 客户端构建时 `unplugin-gem` 把 `globalThis.__GEM_SSR__` 替换成 `undefined`，SSR 代码会被压缩移除
+
+const { get, set, has, deleteProperty, defineProperty, getOwnPropertyDescriptor, ownKeys } = Reflect;
+
+const getRequestScope: (() => WeakMap<object, any> | undefined) | undefined = (globalThis as any).__GEM_SSR__;
+
+/** 服务端渲染时不执行副作用，同步更新 */
+export const isServer = !!getRequestScope;
+
+/**
+ * SSR 时返回当前请求中 `key` 对应的值，第一次访问时使用 `init` 创建，
+ * 不在请求中（包括客户端）时返回 `key` 本身
+ */
+export const getRequestValue: <T extends object>(key: T, init: () => T) => T = getRequestScope
+  ? (key, init) => {
+      const scope = getRequestScope();
+      if (!scope) return key;
+      if (!scope.has(key)) scope.set(key, init());
+      return scope.get(key);
+    }
+  : (key) => key;
+
+/**
+ * SSR 时对象的读写转到当前请求的副本上，副本在第一次访问时从原对象浅复制
+ *
+ * 嵌套的对象没有复制，原地修改会影响所有请求，应该替换顶层属性，例如 `store({ list: [...store.list, item] })`
+ */
+export const isolate: <T extends object>(target: T) => T = getRequestScope
+  ? (target) => {
+      const copy = () => ({ ...target });
+      const current = () => getRequestValue(target, copy);
+      return new Proxy(target, {
+        get: (_, key) => get(current(), key),
+        set: (_, key, value) => set(current(), key, value),
+        has: (_, key) => has(current(), key),
+        deleteProperty: (_, key) => deleteProperty(current(), key),
+        defineProperty: (_, key, descriptor) => defineProperty(current(), key, descriptor),
+        getOwnPropertyDescriptor: (_, key) => getOwnPropertyDescriptor(current(), key),
+        ownKeys: () => ownKeys(current()),
+      });
+    }
+  : (target) => target;

package/src/lib/store.ts

@@ -1,22 +1,53 @@
-import { addMicrotask, createUpdater, type Updater } from './utils';
+import { getRequestValue, isolate, isServer } from './server';
+import { addMicrotask, assignState, createUpdater, type Updater } from './utils';
 
 export type Store<T = any> = Updater<T>;
 
 /**@internal */
 export const _StoreListenerMap = new WeakMap<Store<any>, Set<() => void>>();
 
-export function createStore<T = any>(originStore: T) {
-  const store = createUpdater(originStore, (value?: Partial<T>) => {
-    // biome-ignore lint/plugin/assign: 未知类型
-    Object.assign(store, value);
-    _StoreListenerMap.get(store)?.forEach((func) => addMicrotask(func));
-  });
-  _StoreListenerMap.set(store, new Set<() => void>());
+const createListeners = () => new Set<() => void>();
+
+// SSR 时当前请求中更新过的有 key 的 store，渲染后输出到页面中
+const updatedStores = new Map<string, Store<any>>();
+
+/** SSR 时当前请求中更新过的有 key 的 store，供 `@mantou/gem-ssr` 使用 */
+export const _getUpdatedStores = () => getRequestValue(updatedStores, () => new Map());
+
+// 客户端读取服务端渲染时 store 的值
+let restoreStore: ((key: string) => object | undefined) | undefined;
+
+/** 设置客户端恢复 store 的方法，供 `@mantou/gem-ssr` 使用 */
+export function _setStoreRestorer(restorer: typeof restoreStore) {
+  restoreStore = restorer;
+}
+
+/**
+ * 创建 store，`key` 用来在 SSR 时同步服务端的值，`swc-plugin-gem` 的 `ssr` 选项会为模块顶层的 store 自动添加
+ */
+export function createStore<T = any>(originStore: T, key?: string) {
+  const listeners = createListeners();
+  // SSR 时每个请求使用独立的值
+  const store = isolate(
+    createUpdater(originStore, (value?: Partial<T>) => {
+      assignState(store, value);
+      listeners.forEach(addMicrotask);
+      if (!isServer) return;
+      // SSR 时请求中添加的监听器只属于当前请求，其他请求更新 store 时不会触发
+      getRequestValue(listeners, createListeners).forEach(addMicrotask);
+      const updated = _getUpdatedStores();
+      // 不在请求中时更新的是全局的值，客户端也一样
+      if (key && updated !== updatedStores) updated.set(key, store);
+    }),
+  );
+  if (key && restoreStore) assignState(store, restoreStore(key));
+  _StoreListenerMap.set(store, listeners);
   return store;
 }
 
 export function connect(store: Store<any>, func: () => void) {
-  const listeners = _StoreListenerMap.get(store);
+  const storeListeners = _StoreListenerMap.get(store);
+  const listeners = storeListeners && getRequestValue(storeListeners, createListeners);
   listeners?.add(func);
   return () => listeners?.delete(func);
 }

package/src/lib/utils.ts

@@ -1,4 +1,6 @@
-const { assign, fromEntries, entries, keys } = Object;
+import { getRequestValue } from './server';
+
+const { assign, fromEntries, entries, keys, defineProperty, hasOwn } = Object;
 
 // 用原生 Chrome 找不到调用栈
 function queueMicrotask(cb: () => void) {
@@ -6,13 +8,16 @@ function queueMicrotask(cb: () => void) {
 }
 
 const microtaskSet = new Set<() => void>();
-export function addMicrotask(func: () => void, method = queueMicrotask) {
-  if (microtaskSet.has(func)) return;
-  method(() => {
-    microtaskSet.delete(func);
+const createMicrotaskSet = () => new Set<() => void>();
+export function addMicrotask(func: () => void) {
+  // SSR 时不同请求的同一个函数都需要执行
+  const taskSet = getRequestValue(microtaskSet, createMicrotaskSet);
+  if (taskSet.has(func)) return;
+  queueMicrotask(() => {
+    taskSet.delete(func);
     func();
   });
-  microtaskSet.add(func);
+  taskSet.add(func);
 }
 
 type OverrideFn = {
@@ -29,6 +34,16 @@ type OverrideFn = {
   [Symbol.metadata]: never;
 };
 
+// 删除后继承的 `name` `length` 只读，直接赋值会报错，需要先定义成自有属性
+export function assignState(state: any, payload: any) {
+  for (const key of ['name', 'length']) {
+    if (payload && hasOwn(payload, key)) {
+      defineProperty(state, key, { value: payload[key], writable: true, enumerable: true, configurable: true });
+    }
+  }
+  assign(state, payload);
+}
+
 // 注意 typeof state === 'function' 但是没有 Function 的方法和属性
 export function createUpdater<T, Fn = (payload?: Partial<T>) => any>(initState: T, fn: Fn) {
   const state: any = fn;
@@ -36,7 +51,7 @@ export function createUpdater<T, Fn = (payload?: Partial<T>) => any>(initState:
   // setPrototypeOf(state, null);
   delete state.name;
   delete state.length;
-  assign(state, initState);
+  assignState(state, initState);
   // ts 不允许直接 Omit 掉 Fn 上的属性
   // 只能利用 ts plugin 移除多余的自动完成项
   return state as Fn & Omit<OverrideFn, keyof T> & T;

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = '2.2.13';
+export const version = '2.2.15';

package/src/test/elements/gesture.test.ts

@@ -1,4 +1,4 @@
-import type { EndEventDetail, GemGestureElement, SwipeEventDetail } from '../../elements/gesture';
+import type { EndEventDetail, GemGestureElement, PanEventDetail, SwipeEventDetail } from '../../elements/gesture';
 import { html } from '../../lib/element';
 import { aTimeout, expect, fixture } from '../utils';
 
@@ -240,6 +240,31 @@ describe('GemGestureElement swipe', () => {
     });
   }
 
+  it('locks the axis for the rest of a touch with touch-action=pan-y', async () => {
+    const { el, swipes, dispatch } = await setupGesture('pan-y');
+    const pans: number[] = [];
+    el.addEventListener('pan', (evt: CustomEvent<PanEventDetail>) => pans.push(evt.detail.x));
+    dispatch('pointerdown', [0, 0]);
+    dispatch('pointermove', [10, 0, 20]);
+    dispatch('pointermove', [20, 60, 20]);
+    dispatch('pointerup', [30, 120, 20]);
+    await Promise.resolve();
+    expect(pans).to.deep.equal([0, 0]);
+    expect(swipes).to.deep.equal([]);
+  });
+
+  it('emits raw horizontal movement once locked horizontally with touch-action=pan-y', async () => {
+    const { el, dispatch } = await setupGesture('pan-y');
+    const pans: number[] = [];
+    el.addEventListener('pan', (evt: CustomEvent<PanEventDetail>) => pans.push(evt.detail.x));
+    dispatch('pointerdown', [0, 0]);
+    dispatch('pointermove', [10, 5, 0]);
+    dispatch('pointermove', [20, 15, 0]);
+    dispatch('pointermove', [30, 20, 10]);
+    await Promise.resolve();
+    expect(pans).to.deep.equal([0, 10, 5]);
+  });
+
   it('allows horizontal flicks with touch-action=pan-y', async () => {
     const { swipes, dispatch } = await setupGesture('pan-y');
     dispatch('pointerdown', [0, 0]);

package/src/test/gem-element/basic.test.ts

@@ -161,3 +161,23 @@ describe('基本 gem element 测试', () => {
     expect(el.renderCount).to.equal(2);
   });
 });
+
+@customElement('gem-name-state')
+class GemNameStateElement extends GemElement {
+  state = createState({ name: 'guest' });
+
+  render() {
+    return html`${this.state.name}`;
+  }
+}
+
+describe('state `name` 字段', () => {
+  it('create and update state', async () => {
+    const el: GemNameStateElement = await fixture(html`<gem-name-state></gem-name-state>`);
+    expect(el.textContent).to.equal('guest');
+    el.state({ name: 'admin' });
+    await Promise.resolve();
+    expect({ ...el.state }).to.deep.equal({ name: 'admin' });
+    expect(el.textContent).to.equal('admin');
+  });
+});

package/src/test/store.test.ts

@@ -25,3 +25,15 @@ describe('store 测试', () => {
     expect(flag).to.equal(true);
   });
 });
+
+describe('store `name` `length` 字段', () => {
+  it('create and update store', () => {
+    const store = createStore({ name: 'guest', length: 1 });
+    expect({ ...store }).to.deep.equal({ name: 'guest', length: 1 });
+    store({ name: 'admin', length: 2 });
+    expect({ ...store }).to.deep.equal({ name: 'admin', length: 2 });
+    const store2 = createStore<{ name?: string }>({});
+    store2({ name: 'guest' });
+    expect(store2.name).to.equal('guest');
+  });
+});