@mantou/gem 2.2.14 → 2.2.15

package/src/helper/theme.ts

@@ -1,5 +1,6 @@
 import type { GemElement, Sheet } from '../lib/reactive';
 import { css, SheetToken } from '../lib/reactive';
+import { isServer } from '../lib/server';
 import type { Store } from '../lib/store';
 import { connect, createStore } from '../lib/store';
 import type { Updater } from '../lib/utils';
@@ -118,7 +119,8 @@ export function createDecoratorTheme<T extends Record<string, unknown>>(themeObj
         this.memo(
           () => {
             // https://bugs.webkit.org/show_bug.cgi?id=326327
-            if (CSS.supports(`font:-apple-system-body`)) return theme(access.get(this).apply(this));
+            // SSR 需要更新样式表文本
+            if (isServer || CSS.supports(`font:-apple-system-body`)) return theme(access.get(this).apply(this));
             const next = access.get(this).apply(this);
             const rule = style.cssRules[0] as CSSStyleRule;
             const eleTarget = this.shadowRoot

package/src/lib/decorators.ts

@@ -2,7 +2,7 @@
 
 import type { TemplateResult } from './lit-html';
 import type { Metadata, Sheet } from './reactive';
-import { _createTemplate, _RenderErrorEvent, GemElement, render, UpdateToken } from './reactive';
+import { _createTemplate, _RenderErrorEvent, _renderRoot, GemElement, UpdateToken } from './reactive';
 import type { Store } from './store';
 import { camelToKebabCase, GemError, PropProxyMap } from './utils';
 
@@ -300,8 +300,9 @@ export function template<T extends GemElement, V extends () => TemplateResult |
 export function fallback<T extends GemElement, V extends (err: any) => TemplateResult | null | undefined>() {
   return (_: any, { addInitializer, access }: ClassFieldDecoratorContext<T, V> | ClassMethodDecoratorContext<T, V>) => {
     addInitializer(function (this: T) {
-      this.addEventListener(_RenderErrorEvent, ({ detail }: CustomEvent) => {
-        render(access.get.call(this, this).apply(this, [detail]), this.internals.shadowRoot || this);
+      this.addEventListener(_RenderErrorEvent, (evt: CustomEvent) => {
+        evt.preventDefault();
+        _renderRoot(access.get.call(this, this).apply(this, [evt.detail]), this.internals.shadowRoot || this);
       });
     });
   };

package/src/lib/history.ts

@@ -1,5 +1,6 @@
 // https://github.com/WICG/navigation-api#stakeholder-feedback
 
+import { getRequestValue } from './server';
 import { connect, createStore } from './store';
 import { absoluteLocation, cleanObject, GemError, QueryString } from './utils';
 
@@ -45,7 +46,11 @@ type HistoryParams = Omit<UpdateHistoryParams, 'query'> & {
   hash: string;
 };
 
-const paramsMap = new Map<string, HistoryParams>();
+const globalParamsMap = new Map<string, HistoryParams>();
+// SSR 时每个请求使用独立的记录，请求结束后释放
+// 从全局复制初始记录（设置 basePath 等操作需要它），记录会被原地修改，所以也要复制
+const copyParamsMap = () => new Map([...globalParamsMap].map(([k, v]) => [k, { ...v }]));
+const getParamsMap = () => getRequestValue(globalParamsMap, copyParamsMap);
 
 function validData(data: any) {
   const { $key, $hasCloseHandle, $hasOpenHandle, $hasShouldCloseHandle } = data || {};
@@ -71,8 +76,7 @@ function dispatchBeforeChangeEvent() {
 
 function normalizeParams(params: UpdateHistoryParams): HistoryParams {
   const current =
-    paramsMap.get(store.$key) ||
-    ({ path: getInternalPath(location.pathname), query: new QueryString() } as HistoryParams);
+    gemHistory.getParams() || ({ path: getInternalPath(location.pathname), query: new QueryString() } as HistoryParams);
   // 没提供 path 使用当前 path
   const path = params.path ? absoluteLocation(current.path, params.path) : getInternalPath(location.pathname);
   // 没提供 query 又没有提供 path 时使用当前 search
@@ -100,7 +104,7 @@ function updateHistory(p: UpdateHistoryParams, native: typeof nativeHistory.push
     $title: title,
     ...data,
   };
-  paramsMap.set(state.$key, params);
+  getParamsMap().set(state.$key, params);
   dispatchBeforeChangeEvent();
   cleanObject(store);
   store(state);
@@ -120,7 +124,7 @@ function updateHistoryByNative(data: any, title: string, originUrl: string, nati
   };
   const { pathname, search, hash } = new URL(originUrl, location.origin + location.pathname);
   const params = normalizeParams({ path: pathname, query: new QueryString(search), hash, title, data });
-  paramsMap.set(state.$key, params);
+  getParamsMap().set(state.$key, params);
   dispatchBeforeChangeEvent();
   cleanObject(store);
   store(state);
@@ -149,13 +153,13 @@ class GemHistory extends EventTarget {
     // 应用初始化的时候设置
     gemBasePathStore({ basePath });
     // paramsMap 更新后 ui 才会更新
-    Object.assign(paramsMap.get(store.$key)!, { path: getInternalPath(location.pathname) });
+    Object.assign(this.getParams(), { path: getInternalPath(location.pathname) });
   }
   getParams() {
-    return paramsMap.get(store.$key)!;
+    return getParamsMap().get(store.$key)!;
   }
   updateParams(params: UpdateHistoryParams) {
-    Object.assign(paramsMap.get(store.$key)!, params);
+    Object.assign(this.getParams(), params);
     store();
   }
   push(params: UpdateHistoryParams) {
@@ -166,7 +170,7 @@ class GemHistory extends EventTarget {
   }
   pushIgnoreCloseHandle(params: UpdateHistoryParams) {
     if (store.$hasCloseHandle) {
-      paramsMap.get(store.$key)?.close?.();
+      this.getParams()?.close?.();
       this.replace(params);
     } else {
       this.push(params);
@@ -218,7 +222,7 @@ if (!globalThis._GEMHISTORY) {
   } else if (nativeHistory.state.$hasCloseHandle) {
     store(nativeHistory.state);
     const params = normalizeParams({ title: document.title });
-    paramsMap.set(store.$key, params);
+    getParamsMap().set(store.$key, params);
     // 有 handle 返回键的页面刷新需要清除返回 handler
     gemHistory.back();
   } else {
@@ -228,11 +232,11 @@ if (!globalThis._GEMHISTORY) {
       $key: getKey(),
       ...(nativeHistory.state || {}),
     });
-    paramsMap.set(store.$key, params);
+    getParamsMap().set(store.$key, params);
   }
 
   connect(gemTitleStore, () => {
-    const params = paramsMap.get(store.$key);
+    const params = gemHistory.getParams();
     if (params) {
       params.title = gemTitleStore.title;
     }
@@ -266,9 +270,9 @@ if (!globalThis._GEMHISTORY) {
     // 刷新后再导航需要从当前 state 中构建 params
     // 理论上该条历史记录中不会出现事件处理器
     // 子 app 导航也需要从 state 中构建 params
-    if (!paramsMap.has(newState.$key)) {
+    if (!getParamsMap().has(newState.$key)) {
       const { pathname, search, hash } = location;
-      paramsMap.set(newState.$key, {
+      getParamsMap().set(newState.$key, {
         path: getInternalPath(pathname),
         query: new QueryString(search),
         hash: decodeURIComponent(hash),
@@ -284,9 +288,9 @@ if (!globalThis._GEMHISTORY) {
       // 返回键关闭的 modal 能前进键重新打开
       // 刷新后不能工作：刷新后 historyItem 中只有 url
       // 能在子 app 中工作
-      paramsMap.get(newState.$key)?.open?.();
+      getParamsMap().get(newState.$key)?.open?.();
     } else if (prevState.$hasCloseHandle) {
-      const prevParams = paramsMap.get(prevState.$key);
+      const prevParams = getParamsMap().get(prevState.$key);
       const closeHandle = prevParams?.close;
       const shouldCloseHandle = prevParams?.shouldClose;
       const notAllowClose = shouldCloseHandle && !shouldCloseHandle();

package/src/lib/lit-html.ts

@@ -245,8 +245,10 @@ function trustFromTemplateString(tsa: TemplateStringsArray, stringFromTSA: strin
  * @return Array containing `[html, attrNames]` (array returned for terseness,
  *     to avoid object fields since this code is shared with non-minified SSR
  *     code)
+ *
+ * Gem Note: export for SSR
  */
-const getTemplateHtml = (strings: TemplateStringsArray, type: ResultType): [TrustedHTML, Array<string>] => {
+export const getTemplateHtml = (strings: TemplateStringsArray, type: ResultType): [TrustedHTML, Array<string>] => {
   // Insert makers into the template HTML to represent the position of
   // bindings. The following code scans the template strings to determine the
   // syntactic position of the bindings. They can be in text position, where

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.14';
+export const version = '2.2.15';

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');
+  });
+});