@mantou/gem 2.2.14 → 2.3.0

package/src/helper/i18n.ts

@@ -2,6 +2,7 @@ import type { RouteTrigger } from '../elements/base/route';
 import type { UpdateHistoryParams } from '../lib/history';
 import type { TemplateResult } from '../lib/lit-html';
 import { html, UpdateToken } from '../lib/reactive';
+import { isolate } from '../lib/server';
 import { GemError } from '../lib/utils';
 import { logger } from './logger';
 
@@ -65,13 +66,23 @@ interface I18nOptions<T> {
 export class I18n<T = Record<string, Msg>> implements RouteTrigger {
   resources: Resources<T>;
   fallbackLanguage: string;
-  currentLanguage: string;
   cache?: boolean | 'manual';
   cachePrefix = 'gem-i18n';
   urlParamsType?: 'path' | 'querystring' | 'ccTLD' | 'gTLD';
   urlParamsName?: string;
   onChange?: (currentLanguage: string) => void;
 
+  // SSR 时每个请求使用独立的语言
+  #state = isolate({ currentLanguage: '' });
+
+  get currentLanguage() {
+    return this.#state.currentLanguage;
+  }
+
+  set currentLanguage(lang: string) {
+    this.#state.currentLanguage = lang;
+  }
+
   // 兼容 `<gem-route>`
   replace = ({ path }: UpdateHistoryParams) => this.setLanguage(path!);
   getParams = () => ({ path: this.currentLanguage });

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';
@@ -25,8 +26,11 @@ export function getThemeProps<T>(theme: Theme<T>) {
   return themePropsMap.get(theme) as Theme<T>;
 }
 
-function createThemeFromProps<T extends Record<string, unknown>>(themeObj: T, props: Record<string, string> = {}) {
-  const salt = randomStr();
+function createThemeFromProps<T extends Record<string, unknown>>(
+  themeObj: T,
+  props: Record<string, string> = {},
+  salt = randomStr(),
+) {
   const styleSheet = css({})[SheetToken];
   const store = createStore<T>(themeObj);
   // 同步分配变量名，新增的键在更新后立即可读；样式内容随 store 异步更新
@@ -74,14 +78,17 @@ function createThemeFromProps<T extends Record<string, unknown>>(themeObj: T, pr
 
 /**
  * 用于 `@adoptedStyle(theme)`，类似 `css`
+ *
+ * `key` 用作 css 变量名的后缀，SSR 时让服务端和客户端的变量名一致，
+ * `swc-plugin-gem` 的 `ssr` 选项会为模块顶层的主题自动添加
  */
-export function createScopedTheme<T extends Record<string, unknown>>(themeObj: T) {
-  return createThemeFromProps(themeObj);
+export function createScopedTheme<T extends Record<string, unknown>>(themeObj: T, key?: string) {
+  return createThemeFromProps(themeObj, {}, key);
 }
 
-/** 全局主题 */
-export function createTheme<T extends Record<string, unknown>>(themeObj: T) {
-  const result = createScopedTheme(themeObj);
+/** 全局主题，`key` 同 `createScopedTheme` */
+export function createTheme<T extends Record<string, unknown>>(themeObj: T, key?: string) {
+  const result = createScopedTheme(themeObj, key);
   document.adoptedStyleSheets.push(result[SheetToken].getStyle());
   return result;
 }
@@ -93,6 +100,7 @@ export function createOverrideTheme<T extends Record<string, unknown>>(theme: Th
 
 /**
  * 返回一个主题对象，但同时又是一个装饰器函数，用来装饰一个主题更新函数
+ * 所有实例共享变量名，`key` 同 `createScopedTheme`
  *
  * @example
  * ```ts
@@ -103,8 +111,8 @@ export function createOverrideTheme<T extends Record<string, unknown>>(theme: Th
  * }
  * ```
  * */
-export function createDecoratorTheme<T extends Record<string, unknown>>(themeObj: T) {
-  const themeAsKeys = createThemeFromProps(themeObj);
+export function createDecoratorTheme<T extends Record<string, unknown>>(themeObj: T, key?: string) {
+  const themeAsKeys = createThemeFromProps(themeObj, {}, key);
   const props = getThemeProps(themeAsKeys);
   const update = <E extends GemElement, V extends () => T, K = any[] | undefined>(
     getDep?: K extends readonly any[] ? (instance: E) => K : undefined,
@@ -118,7 +126,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,12 +2,12 @@
 
 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';
 
 type GemElementPrototype = GemElement & { '': never };
-type StaticField = Exclude<keyof Metadata, keyof ShadowRootInit | 'aria' | 'noBlocking' | 'penetrable'>;
+type StaticField = Exclude<keyof Metadata, keyof ShadowRootInit | 'aria' | 'noBlocking' | 'penetrable' | 'attrProps'>;
 
 const { deleteProperty, getOwnPropertyDescriptor, defineProperty } = Reflect;
 const { getPrototypeOf, assign, hasOwn } = Object;
@@ -32,12 +32,31 @@ function clearField<T extends GemElement>(instance: T, prop: string) {
   (instance as any)[prop] = value;
 }
 
-const observedTargetAttributes = new WeakMap<GemElementPrototype, Map<string, string>>();
+/**
+ * 定义响应式的成员：在原型上定义访问器（基类定义过就跳过），移除实例上的同名字段，
+ * `field` 记录到元数据中，供外部读取
+ */
+function defineMember(
+  context: ClassFieldDecoratorContext,
+  field: StaticField,
+  name: string,
+  define: (target: GemElementPrototype, prop: string) => void,
+) {
+  const prop = context.name as string;
+  pushStaticField(context, field, name);
+  context.addInitializer(function (this: GemElement) {
+    const target = getDecoratorTarget(this, context);
+    if (!hasOwn(target, prop)) define(target, prop);
+    clearField(this, prop);
+  });
+}
+
 // hack 修改 attribute 行为，如果是观察的，就使用 `setter`
 // 不在 Devtools 中工作 https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#dom_access
 // 使用 Gem DevTools 注入脚本监听 attribute 变化
 const { setAttribute, toggleAttribute, removeAttribute } = Element.prototype;
-const getObservedPropName = (i: GemElement, n: string) => observedTargetAttributes.get(getPrototypeOf(i))?.get(n);
+const getObservedPropName = (i: GemElement, n: string) =>
+  ((i.constructor as any)[Symbol.metadata] as Metadata | undefined)?.attrProps?.[n];
 GemElement.prototype.setAttribute = function (n: string, v: string) {
   const prop = getObservedPropName(this, n);
   if (!prop) return setAttribute.call(this, n, v);
@@ -130,19 +149,12 @@ type AttrType = BooleanConstructor | NumberConstructor | StringConstructor;
 function decoratorAttr<T extends GemElement>(context: ClassFieldDecoratorContext<T>, attrType: AttrType) {
   const prop = context.name as string;
   const attr = camelToKebabCase(prop);
-  context.addInitializer(function (this: T) {
-    const target = getDecoratorTarget(this, context);
-    if (!hasOwn(target, prop)) {
-      pushStaticField(context, 'observedAttributes', attr); // 没有 observe 的效果
-      defineProp(target, prop, { attr, attrType });
-    }
-    clearField(this, prop);
-    // 记录观察的 attribute, 用于 hack 的 setAttribute
-    const proto = getPrototypeOf(this);
-    const attrMap = observedTargetAttributes.get(proto) || new Map<string, string>();
-    attrMap.set(attr, prop);
-    observedTargetAttributes.set(proto, attrMap);
-  });
+  const metadata = context.metadata as Metadata;
+  // 记录观察的 attribute，用于 hack 的 setAttribute，原型链继承基类的记录
+  if (!hasOwn(metadata, 'attrProps')) metadata.attrProps = Object.create(metadata.attrProps || null);
+  metadata.attrProps![attr] = prop;
+  // `observedAttributes` 没有 observe 的效果
+  defineMember(context, 'observedAttributes', attr, (target) => defineProp(target, prop, { attr, attrType }));
   // 延时定义的元素需要继承原实例属性值
   return function (this: any, initValue: any) {
     return this.getAttribute(attr) ?? initValue;
@@ -181,14 +193,7 @@ export function numattribute<T extends GemElement>(_: undefined, context: ClassF
  */
 export function property<T extends GemElement>(_: undefined, context: ClassFieldDecoratorContext<T>) {
   const prop = context.name as string;
-  context.addInitializer(function (this: T) {
-    const target = getDecoratorTarget(this, context);
-    if (!hasOwn(target, prop)) {
-      pushStaticField(context, 'observedProperties', prop);
-      defineProp(target, prop);
-    }
-    clearField(this, prop);
-  });
+  defineMember(context, 'observedProperties', prop, defineProp);
   // 延时定义的元素需要继承原实例属性值
   return function (this: any, initValue: any) {
     return this[prop] ?? initValue;
@@ -300,8 +305,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);
       });
     });
   };
@@ -341,16 +347,8 @@ function defineCSSState(target: GemElementPrototype, prop: string, stateStr: str
  * ```
  */
 export function state<T extends GemElement>(_: undefined, context: ClassFieldDecoratorContext<T, boolean>) {
-  const prop = context.name as string;
-  const attr = camelToKebabCase(prop);
-  context.addInitializer(function (this: T) {
-    const target = getDecoratorTarget(this, context);
-    if (!hasOwn(target, prop)) {
-      pushStaticField(context, 'definedCSSStates', attr);
-      defineCSSState(target, prop, attr);
-    }
-    clearField(this, prop);
-  });
+  const stateStr = camelToKebabCase(context.name as string);
+  defineMember(context, 'definedCSSStates', stateStr, (target, prop) => defineCSSState(target, prop, stateStr));
 }
 
 function defineStaticField(
@@ -435,20 +433,9 @@ export function emitter<T extends GemElement>(_: undefined, context: ClassFieldD
 export function globalemitter<T extends GemElement>(_: undefined, context: ClassFieldDecoratorContext<T, Emitter>) {
   defineEmitter(context, { bubbles: true, composed: true });
 }
-function defineEmitter<T extends GemElement>(
-  context: ClassFieldDecoratorContext,
-  eventOptions?: Omit<CustomEventInit<unknown>, 'detail'>,
-) {
-  const prop = context.name as string;
-  const event = camelToKebabCase(prop);
-  context.addInitializer(function (this: T) {
-    const target = getDecoratorTarget(this, context);
-    if (!hasOwn(target, prop)) {
-      pushStaticField(context, 'definedEvents', event);
-      defineProp(target, prop, { event, eventOptions });
-    }
-    clearField(this, prop);
-  });
+function defineEmitter(context: ClassFieldDecoratorContext, eventOptions?: Omit<CustomEventInit<unknown>, 'detail'>) {
+  const event = camelToKebabCase(context.name as string);
+  defineMember(context, 'definedEvents', event, (target, prop) => defineProp(target, prop, { event, eventOptions }));
 }
 
 /**

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,15 +46,20 @@ 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);
+
+// 内部状态字段，不能由外部设置
+const internalStateKeys = ['$key', '$hasCloseHandle', '$hasOpenHandle', '$hasShouldCloseHandle'] as const;
 
 function validData(data: any) {
-  const { $key, $hasCloseHandle, $hasOpenHandle, $hasShouldCloseHandle } = data || {};
-  if (store.$key === $key) return;
-  if ($key) throw new GemError('`$key` is not allowed');
-  if ($hasCloseHandle) throw new GemError('`$hasCloseHandle` is not allowed');
-  if ($hasOpenHandle) throw new GemError('`$hasOpenHandle` is not allowed');
-  if ($hasShouldCloseHandle) throw new GemError('`$hasShouldCloseHandle` is not allowed');
+  if (store.$key === data?.$key) return;
+  for (const key of internalStateKeys) {
+    if (data?.[key]) throw new GemError(`\`${key}\` is not allowed`);
+  }
 }
 
 function getUrlBarPath(internalPath: string) {
@@ -65,14 +71,17 @@ function getInternalPath(urlBarPath: string) {
   return urlBarPath.replace(new RegExp(`^${gemHistory.basePath}/`), '/');
 }
 
-function dispatchBeforeChangeEvent() {
+// 切换到新的历史记录状态
+function changeState(state: HistoryState) {
   gemHistory.dispatchEvent(new CustomEvent('beforechange'));
+  cleanObject(store);
+  store(state);
 }
 
 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(), title: document.title } as HistoryParams);
   // 没提供 path 使用当前 path
   const path = params.path ? absoluteLocation(current.path, params.path) : getInternalPath(location.pathname);
   // 没提供 query 又没有提供 path 时使用当前 search
@@ -80,8 +89,9 @@ function normalizeParams(params: UpdateHistoryParams): HistoryParams {
   const queryChanged = String(newQueryObject) !== String(current.query);
   const query = queryChanged ? newQueryObject : current.query;
   const urlChanged = path !== current.path || queryChanged;
-  // 没提供 title 又没有改变 URL 时使用当前 document.title
-  const title = params.title || (urlChanged ? '' : document.title);
+  // 没提供 title 又没有改变 URL 时使用当前 title
+  // 不使用 document.title，它可能已被格式化（例如添加了网站名后缀）
+  const title = params.title || (urlChanged ? '' : current.title);
   const statusChanged = params.close || params.data || params.open || params.shouldClose;
   // 没提供 hash 又没有改变 URL 仅仅是状态更新时使用当前 hash
   const hash = decodeURIComponent(params.hash ?? (!urlChanged && statusChanged ? location.hash : ''));
@@ -100,10 +110,8 @@ function updateHistory(p: UpdateHistoryParams, native: typeof nativeHistory.push
     $title: title,
     ...data,
   };
-  paramsMap.set(state.$key, params);
-  dispatchBeforeChangeEvent();
-  cleanObject(store);
-  store(state);
+  getParamsMap().set(state.$key, params);
+  changeState(state);
   const url = getUrlBarPath(path) + new QueryString(query) + hash;
   const prevHash = decodeURIComponent(location.hash);
   native(state, title, url);
@@ -112,23 +120,8 @@ function updateHistory(p: UpdateHistoryParams, native: typeof nativeHistory.push
 
 // 跨框架时，调用者对 basePath 无感知
 function updateHistoryByNative(data: any, title: string, originUrl: string, native: typeof nativeHistory.pushState) {
-  validData(data);
-  const state = {
-    $key: getKey(),
-    $title: title,
-    ...(data || {}),
-  };
   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);
-  dispatchBeforeChangeEvent();
-  cleanObject(store);
-  store(state);
-  const url = getUrlBarPath(pathname) + params.query + hash;
-  const prevHash = location.hash;
-  native(state, title, url);
-  // `location.hash` 和 `hash` 都已经进行了 url 编码，可以直接进行相等判断
-  if (prevHash !== hash) dispatchEvent(new CustomEvent('hashchange'));
+  updateHistory({ path: pathname, query: search, hash, title, data }, native);
 }
 
 const gemBasePathStore = createStore({
@@ -149,13 +142,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 +159,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 +211,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 +221,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 +259,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 +277,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();
@@ -309,9 +302,7 @@ if (!globalThis._GEMHISTORY) {
       }
     }
 
-    dispatchBeforeChangeEvent();
-    cleanObject(store);
-    store(newState);
+    changeState(newState);
   });
 }
 

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