@mantou/gem 2.3.0 → 2.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mantou/gem",
-  "version": "2.3.0",
-  "description": "💎 使用自定义元素的轻量级 WebApp 开发框架",
+  "version": "2.3.2",
+  "description": "💎 Build reusable custom elements and web apps on Web Components",
   "keywords": [
     "frontend",
     "web components",
@@ -22,6 +22,7 @@
     "./helper/*": "./helper/*.js"
   },
   "files": [
+    "/AGENTS.md",
     "/index.*",
     "/dist/",
     "/elements/",
@@ -33,14 +34,14 @@
   "scripts": {
     "docs": "gem-book docs",
     "build:docs": "gem-book build docs",
-    "build:module": "tsc -p tsconfig.build.json",
+    "build:module": "tsrs -p tsconfig.build.json",
     "build:lib": "rslib build",
     "build": "pnpm build:module && pnpm build:lib",
     "start": "pnpm build:module --watch",
     "test": "cross-env wtr"
   },
   "devDependencies": {
-    "@gemjs/config": "^2.1.3",
+    "@gemjs/config": "^2.1.4",
     "@rslib/core": "^0.23.0",
     "@swc/helpers": "^0.5.23",
     "@types/chai": "^5.0.0",
@@ -50,7 +51,7 @@
     "@web/test-runner": "^0.18.1",
     "chai": "^5.1.1",
     "rimraf": "^3.0.2",
-    "typescript": "^5.6.2"
+    "tsrs": "^0.18.0-ts7.1.0-dev.20260929"
   },
   "author": "mantou132",
   "license": "MIT",

package/src/elements/base/gesture.ts

@@ -137,7 +137,26 @@ const style = css`
     &:where(:not([hidden])) {
       display: block;
       user-select: none;
-      touch-action: attr(touch-action, none);
+      touch-action: none;
+    }
+    /* 常用取值，兼容不支持在 touch-action 中使用 attr() 的浏览器 */
+    &:where([touch-action='auto']) {
+      touch-action: auto;
+    }
+    &:where([touch-action='manipulation']) {
+      touch-action: manipulation;
+    }
+    &:where([touch-action='pan-x']) {
+      touch-action: pan-x;
+    }
+    &:where([touch-action='pan-y']) {
+      touch-action: pan-y;
+    }
+    /* 支持任意取值；不带类型的 attr() 是字符串，对 touch-action 无效 */
+    @supports (touch-action: attr(touch-action type(*), none)) {
+      &:where([touch-action]) {
+        touch-action: attr(touch-action type(*), none);
+      }
     }
   }
 `;

package/src/elements/base/modal-factory.ts

@@ -1,9 +1,27 @@
 import { aria, mounted, shadow } from '../../lib/decorators';
 import { history } from '../../lib/history';
 import { GemElement } from '../../lib/reactive';
+import type { Store } from '../../lib/store';
 import { connect, createStore } from '../../lib/store';
 
 const open = Symbol('open mark');
+// 静态方法返回不可伪造的值，防止子类覆盖
+const final = Symbol();
+
+type ModalElement = GemElement & { label: string };
+
+export interface ModalClass<T> extends Omit<typeof GemElement, 'prototype'> {
+  new (): ModalElement;
+  prototype: ModalElement;
+  inertStore: HTMLElement[];
+  instance: GemElement | null;
+  store: Store<{ [open]: boolean } & T>;
+  readonly isOpen: boolean;
+  open(opts: T): typeof final;
+  close(): typeof final;
+  closeHandle(): typeof final;
+  shouldClose(): boolean;
+}
 
 /**
  * 需要使用范型，所以导出一个函数，用来*创建*类似 Confirm 元素的基类;
@@ -13,9 +31,7 @@ const open = Symbol('open mark');
  * 使用 `mounted`/`unmounted` 定义 `open`/`close` 回调;
  * 模拟 top layer：https://github.com/whatwg/html/issues/4633.
  */
-export function createModalClass<T extends Record<string, unknown>>(options: T) {
-  const final = Symbol();
-
+export function createModalClass<T extends Record<string, unknown>>(options: T): ModalClass<T> {
   @shadow()
   @aria({ role: 'alertdialog', ariaModal: 'true' })
   class ModalElement extends GemElement {
@@ -40,7 +56,7 @@ export function createModalClass<T extends Record<string, unknown>>(options: T)
      * 自带 100ms 延迟，以允许在其他 Dialog 的 `shouldClose` 中调用此方法;
      * 浏览器 history 为异步 API，需要设置较长延迟;
      */
-    static open(opts: T) {
+    static open(opts: T): typeof final {
       const instance = new this();
       this.instance = instance;
       this.inertStore = ([...document.body.children] as HTMLElement[]).filter((e) => !e.inert);
@@ -63,7 +79,7 @@ export function createModalClass<T extends Record<string, unknown>>(options: T)
      * @final
      * UI 中执行关闭
      */
-    static close() {
+    static close(): typeof final {
       history.back();
       return final;
     }
@@ -72,7 +88,7 @@ export function createModalClass<T extends Record<string, unknown>>(options: T)
      * @final
      * history 中自动调用
      */
-    static closeHandle() {
+    static closeHandle(): typeof final {
       this.inertStore.forEach((e) => (e.inert = false));
       this.instance?.remove();
       this.store({ [open]: false, ...options });

package/src/elements/base/reflect.ts

@@ -1,9 +1,8 @@
 /**
- * - 预渲染可能造成重复的元素，在序列化时可以用正则移除 GemReflectElement 渲染的从开始到结束连续的元素
- * - `replaceAll(/<!--gem-reflect-start-->.*?<!--gem-reflect-end-->/gs, '')`
+ * 把子节点移动到 `target`（默认 `document.head`）中，用开始和结束注释标记这些节点，
+ * 修改 `target` 或者卸载时一起移动或移除
  *
- * 不能在在顶级代码块中清除这些元素，因为重复加载该代码时会把正常 reflect 元素清除，
- * 比如 duoyun-ui 文档站加载示例元素时把 GemReflectElement 渲染的元素清除
+ * 服务端渲染时不执行 effect，客户端水合后才移动，使用 `getLogicalParent` 从被移动的节点找到 reflect 元素
  */
 
 import { attribute, effect, property, willMount } from '../../lib/decorators';
@@ -25,6 +24,31 @@ const getReflectFragment = (startNode: Comment) => {
   return result;
 };
 
+// 移动到的目标元素和片段开始注释对应的 reflect 元素，向上查找元素时跨越 reflect
+const targets = new WeakSet<Node>();
+const startNodes = new WeakMap<Node, GemReflectElement>();
+
+// 向前查找片段的开始注释，遇到其他片段的结束注释时不在片段中
+const getReflectElement = (node: Node) => {
+  for (let n = node.previousSibling; n; n = n.previousSibling) {
+    const ele = startNodes.get(n);
+    if (ele) return ele;
+    if (n.nodeValue === END) return;
+  }
+};
+
+/**
+ * 节点的逻辑父元素：被 reflect 移动的节点是 reflect 元素，ShadowRoot 中顶层的节点是宿主，其他是父元素
+ */
+export function getLogicalParent(node: Node): Element | null {
+  const parent = node.parentNode;
+  if (parent && targets.has(parent)) {
+    const ele = getReflectElement(node);
+    if (ele) return ele;
+  }
+  return parent instanceof ShadowRoot ? parent.host : node.parentElement;
+}
+
 export class GemReflectElement extends GemElement {
   @attribute method: 'prepend' | 'append';
 
@@ -45,6 +69,8 @@ export class GemReflectElement extends GemElement {
 
   @effect((i) => [i.target])
   #changeTarget = () => {
+    targets.add(this.target);
+    startNodes.set(this.#startNode, this);
     (this.#childNodes || [this.#startNode, ...this.childNodes, this.#endNode]).forEach((node, index, arr) => {
       const prev = arr[index - 1];
       if (prev) {

package/src/elements/base/route.ts

@@ -12,12 +12,6 @@ import { addListener } from '../../lib/utils';
 type Params = Record<string, string>;
 type Matcher = (path: string) => Params | null | undefined;
 
-declare global {
-  // https://bugzilla.mozilla.org/show_bug.cgi?id=1731418
-  // https://github.com/WebKit/standards-positions/issues/61
-  var URLPattern: any;
-}
-
 const UNNAMED_PARAM_PREFIX = '_';
 
 // 不支持 `URLPattern` 时转换成正则
@@ -56,7 +50,8 @@ function createMatcher(pattern: string): Matcher {
   const urlPattern = new URLPattern({ pathname: pattern });
   // 参数前的 `/` 可能是可选的，例如 `/a/:b?` 匹配 `/a`
   const prefix = literal.replace(/\/$/, '');
-  return (path) => (path.startsWith(prefix) ? urlPattern.exec({ pathname: path })?.pathname.groups : null);
+  return (path) =>
+    path.startsWith(prefix) ? (urlPattern.exec({ pathname: path })?.pathname.groups as Params | undefined) : null;
 }
 
 // pattern 来自路由定义，数量有限

package/src/helper/i18n.ts

@@ -2,7 +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 { isolate, isServer, ssrHooks } from '../lib/server';
 import { GemError } from '../lib/utils';
 import { logger } from './logger';
 
@@ -26,7 +26,8 @@ export function splice(rawValue: string, ...rest: (((s: string) => TemplateResul
   return html(templateArr, ...values);
 }
 
-const modules = new Set<I18n<any>>();
+// 正在创建子模块，构造函数中用来区分主模块
+let creatingSubModule = false;
 
 type Msg =
   | {
@@ -35,13 +36,20 @@ type Msg =
     }
   | string;
 
-export type I18nJSON<T> = {
+type I18nJSON<T> = {
   currentLanguage: string;
   currentLanguagePack: Partial<T>;
 };
 
+/**
+ * 语言包加载函数，例如 `() => import('./zh.json')`，打包时每个语言是单独的文件，只加载用到的语言
+ *
+ * 类型只从 `default` 推断，否则模块对象本身也会被推断成语言包
+ */
+type PackLoader<T> = () => Promise<{ default: Partial<T> } | NoInfer<Partial<T>>>;
+
 interface Resources<T> {
-  [key: string]: Partial<T> | string;
+  [key: string]: Partial<T> | PackLoader<T>;
 }
 
 interface I18nOptions<T> {
@@ -50,12 +58,12 @@ interface I18nOptions<T> {
   // 可以在构造函数中指定，但会被 URL 中的语言参数覆盖
   currentLanguage?: string;
   /**
-   * `true` 表示在修改语言时自动缓存。
-   * 为了避免缓存超出 `localStorage` 限制，语言包 URL 应该带版本号查询参数
+   * 缓存用户选择的语言，`true` 表示在修改语言时自动缓存，`manual` 时调用 `setCache` 缓存
+   *
+   * 同时缓存加载函数加载的语言包，下次加载完成前先使用缓存，加载完成后更新
    */
   cache?: boolean | 'manual';
-  // lib 需要设置，避免被应用中的 i18n 一起清理掉语言缓存
-  // 也用来作为 prerender 的 script type
+  // 缓存和 SSR 输出的 key，lib 需要设置，避免和应用中的 i18n 冲突
   cachePrefix?: string;
   // 为 `path` 时页面的路由不能和语言代码相同
   urlParamsType?: 'path' | 'querystring' | 'ccTLD' | 'gTLD';
@@ -72,8 +80,12 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
   urlParamsName?: string;
   onChange?: (currentLanguage: string) => void;
 
-  // SSR 时每个请求使用独立的语言
-  #state = isolate({ currentLanguage: '' });
+  // SSR 时每个请求使用独立的语言，`pending` 是正在切换的语言
+  #state = isolate({ currentLanguage: '', pending: undefined as Promise<string> | undefined });
+
+  // 子模块跟随主模块切换语言，不修改文档的语言，也不缓存语言，只缓存语言包
+  #isSub = creatingSubModule;
+  #subModules = new Set<I18n<any>>();
 
   get currentLanguage() {
     return this.#state.currentLanguage;
@@ -83,14 +95,23 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
     this.#state.currentLanguage = lang;
   }
 
+  /** 等待切换语言完成，包括加载语言包和所有子模块，例如渲染刚加载的模块前 */
+  get ready(): Promise<unknown> {
+    return Promise.all([this.#state.pending, ...[...this.#subModules].map((i18n) => i18n.ready)]);
+  }
+
   // 兼容 `<gem-route>`
   replace = ({ path }: UpdateHistoryParams) => this.setLanguage(path!);
   getParams = () => ({ path: this.currentLanguage });
 
-  get #cacheCurrentKey() {
+  get #cacheKey() {
     return `${this.cachePrefix}:current`;
   }
 
+  get #storeKey() {
+    return `i18n:${this.cachePrefix}`;
+  }
+
   get #urlParamsLang() {
     const { hostname, pathname, search } = location;
     const parts = hostname.split('.');
@@ -109,21 +130,27 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
   }
 
   get #cacheLang() {
-    return (this.cache && localStorage.getItem(this.#cacheCurrentKey)) || '';
-  }
-
-  get #isMain(): boolean {
-    return !modules.has(this);
+    return (!this.#isSub && this.cache && localStorage.getItem(this.#cacheKey)) || '';
   }
 
   set #lang(lang: string) {
-    if (this.#isMain) {
-      document.documentElement.lang = lang;
-    }
+    if (!this.#isSub) document.documentElement.lang = lang;
     this.currentLanguage = lang;
     this.onChange?.(lang);
   }
 
+  /**
+   * SSR 时使用过的模块记录到 store 中，渲染结束时读取，输出当前语言的语言包，
+   * 客户端构造时恢复，不需要再加载
+   */
+  #ssrData = Object.defineProperties(
+    {},
+    {
+      currentLanguage: { enumerable: true, get: () => this.currentLanguage },
+      currentLanguagePack: { enumerable: true, get: () => this.#getCompletePack() },
+    },
+  );
+
   #inConstructor = true;
   constructor(options: I18nOptions<T>) {
     if (!options.resources[options.fallbackLanguage]) {
@@ -132,35 +159,49 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
 
     Object.assign<I18n<T>, I18nOptions<T>>(this as I18n<T>, options);
 
-    let currentLanguage = this.#urlParamsLang || this.currentLanguage || this.#cacheLang;
+    const ssrData = isServer ? undefined : (ssrHooks.createStore?.(this.#storeKey) as I18nJSON<T> | undefined);
+    // 已经包含后备语言中的消息
+    if (ssrData) this.resources[ssrData.currentLanguage] = ssrData.currentLanguagePack;
 
-    const ele = document.querySelector(`[type*=${this.cachePrefix}]`);
-    if (ele) {
-      try {
-        const prerenderData = JSON.parse(ele.textContent || '') as I18nJSON<T>;
-        currentLanguage = prerenderData.currentLanguage;
-        this.resources[prerenderData.currentLanguage] = prerenderData.currentLanguagePack;
-      } catch {
-        //
-      }
-    }
+    // 子模块使用主模块当前的语言，可能和服务端输出时不同，例如客户端切换过语言
+    const lang = this.#isSub
+      ? this.currentLanguage || ssrData?.currentLanguage
+      : ssrData?.currentLanguage || this.#urlParamsLang || this.currentLanguage || this.#cacheLang;
 
-    if (currentLanguage) {
-      this.#lang = currentLanguage;
-      this.setLanguage(currentLanguage);
+    if (lang) {
+      this.#lang = lang;
+      this.setLanguage(lang);
     } else {
       this.resetLanguage();
     }
     this.#inConstructor = false;
   }
 
+  #getPack(lang: string): Record<string, Msg> | undefined {
+    const data = this.resources[lang];
+    return data && typeof data === 'object' ? (data as any) : undefined;
+  }
+
+  /** 当前语言包，包含后备语言中的消息，服务端输出后客户端不需要再加载后备语言 */
+  #getCompletePack() {
+    const pack: Record<string, Msg> = { ...this.#getPack(this.fallbackLanguage) };
+    for (const [key, msg] of Object.entries(this.#getPack(this.currentLanguage) || {})) {
+      if (msg) pack[key] = msg;
+    }
+    return pack as Partial<T>;
+  }
+
   get(s: keyof T): string;
   get(s: keyof T, ...rest: (((str: string) => TemplateResult) | string)[]): TemplateResult;
   get(s: keyof T, ...rest: (((str: string) => TemplateResult) | string)[]) {
-    const currentLanguagePack = this.resources[this.currentLanguage] as any;
-    const fallbackLanguagePack = this.resources[this.fallbackLanguage] as any;
-    const msg = currentLanguagePack[s] || fallbackLanguagePack[s];
-    const rawValue: string = msg?.message || msg || `[${s as string}]`;
+    if (isServer) ssrHooks.updateStore?.(this.#storeKey, this.#ssrData);
+    const key = s as string;
+    const currentPack = this.#getPack(this.currentLanguage);
+    const fallbackPack = this.#getPack(this.fallbackLanguage);
+    const msg = currentPack?.[key] || fallbackPack?.[key];
+    // 客户端只加载当前语言，缺少消息时才加载后备语言
+    if (!msg && currentPack && !fallbackPack) this.#loadFallback();
+    const rawValue: string = (typeof msg === 'object' ? msg.message : msg) || `[${key}]`;
     if (!rest.length) return rawValue;
     return splice(rawValue, ...rest);
   }
@@ -175,116 +216,132 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
     return this.fallbackLanguage;
   }
 
-  async setLanguage(lang: string): Promise<string> {
-    if (this.#isMain) {
-      modules.forEach(async (i18n) => await i18n.setLanguage(lang));
-    }
-    let pack: Partial<T>;
-    const data = this.resources[lang];
-    if (!data) {
-      logger.warn(`${this.cachePrefix}: not found \`${lang}\``);
-      return this.resetLanguage();
-    }
+  #packCacheKey(lang: string) {
+    return `${this.cachePrefix}:pack:${lang}`;
+  }
 
-    if (typeof data === 'string') {
-      const prefix = `${this.cachePrefix}:`;
-      const localKey = `${prefix}${data}`;
-      const localPackString = localStorage.getItem(localKey);
-
-      const fetchPack = async () => {
-        const pkg = await (await fetch(data)).json();
-        if (this.cache) {
-          // 移除之前的版本缓存
-          for (let i = 0; i < localStorage.length; i++) {
-            const key = localStorage.key(i) as string;
-            if (key.startsWith(prefix)) {
-              localStorage.removeItem(key);
-            }
-          }
-          localStorage.setItem(localKey, JSON.stringify(pkg));
-        }
-        return pkg;
-      };
-
-      if (localPackString) {
-        try {
-          pack = JSON.parse(localPackString);
-        } catch {
-          pack = await fetchPack();
-        }
-      } else {
-        pack = await fetchPack();
-      }
-    } else {
-      pack = data;
+  #readPackCache(lang: string): Partial<T> | undefined {
+    if (!this.cache || isServer) return;
+    try {
+      return JSON.parse(localStorage.getItem(this.#packCacheKey(lang)) || 'null') || undefined;
+    } catch {
+      //
     }
-    this.resources[lang] = pack;
-
-    if (!this.#inConstructor) {
-      // 更新所有元素，可能会更新许多不必要的元素
-      const temp: Element[] = [document.documentElement];
-      while (temp.length) {
-        const element = temp.pop()!;
-        (element as any)[UpdateToken]?.();
-        // 和 gem 更新机制一样使用深度优先
-        temp.push(...[...element.children, ...(element.shadowRoot?.children || [])].reverse());
+  }
+
+  /** 缓存语言包，只保留正在使用的语言，返回内容是否和缓存不同 */
+  #writePackCache(lang: string, pack: Partial<T>) {
+    if (!this.cache || isServer) return false;
+    const key = this.#packCacheKey(lang);
+    const json = JSON.stringify(pack);
+    try {
+      if (localStorage.getItem(key) === json) return false;
+      const keep = new Set([lang, this.currentLanguage, this.fallbackLanguage].map((e) => this.#packCacheKey(e)));
+      const prefix = this.#packCacheKey('');
+      for (const k of Object.keys(localStorage)) {
+        if (k.startsWith(prefix) && !keep.has(k)) localStorage.removeItem(k);
       }
+      localStorage.setItem(key, json);
+    } catch {
+      // 例如超出存储限制
     }
+    return true;
+  }
 
-    if (lang !== this.currentLanguage) {
-      this.#lang = lang;
+  /** 已经加载时同步返回，避免构造函数中异步更新，有缓存时先使用缓存，加载完成后更新 */
+  #loadPack(lang: string): Partial<T> | Promise<Partial<T>> {
+    const data = this.resources[lang];
+    if (typeof data !== 'function') return data;
+    const cached = this.#readPackCache(lang);
+    const loading = data().then((mod: any) => {
+      const pack = (mod && typeof mod.default === 'object' ? mod.default : mod) as Partial<T>;
+      this.resources[lang] = pack;
+      if (this.#writePackCache(lang, pack) && cached) this.#updateElements();
+      return pack;
+    });
+    if (!cached) return loading;
+    // 加载失败时继续使用缓存
+    loading.catch((err) => logger.warn(`${this.cachePrefix}: failed to load \`${lang}\``, err));
+    this.resources[lang] = cached;
+    return cached;
+  }
+
+  #fallbackLoading?: Promise<unknown>;
+  #loadFallback() {
+    this.#fallbackLoading ||= Promise.resolve(this.#loadPack(this.fallbackLanguage)).then(() => this.#updateElements());
+  }
+
+  // 更新所有元素，可能会更新许多不必要的元素
+  #updateElements() {
+    const temp: Element[] = [document.documentElement];
+    while (temp.length) {
+      const element = temp.pop()!;
+      (element as any)[UpdateToken]?.();
+      // 和 gem 更新机制一样使用深度优先
+      temp.push(...[...element.children, ...(element.shadowRoot?.children || [])].reverse());
     }
-    // auto cache
-    if (this.cache === true) {
-      this.setCache();
+  }
+
+  setLanguage(lang: string): Promise<string> {
+    const promise = this.#setLanguage(lang);
+    this.#state.pending = promise;
+    return promise;
+  }
+
+  async #setLanguage(lang: string): Promise<string> {
+    if (!this.resources[lang]) {
+      logger.warn(`${this.cachePrefix}: not found \`${lang}\``);
+      return this.resetLanguage();
     }
+    const subModules = [...this.#subModules].map((i18n) => i18n.setLanguage(lang));
+
+    // 服务端渲染需要同步读取后备语言中的消息，输出的语言包也包含后备语言的消息
+    const langs = isServer && lang !== this.fallbackLanguage ? [lang, this.fallbackLanguage] : [lang];
+    const packs = langs.map((e) => this.#loadPack(e));
+    if (packs.some((e) => e instanceof Promise)) await Promise.all(packs);
+
+    if (!this.#inConstructor) this.#updateElements();
+    if (lang !== this.currentLanguage) this.#lang = lang;
+    if (this.cache === true) this.setCache();
+    await Promise.all(subModules);
     return lang;
   }
 
   resetLanguage() {
-    if (this.#isMain) {
-      modules.forEach((i18n) => i18n.resetLanguage());
-    }
-    this.#lang = this.fallbackLanguage;
-    if (this.cache) {
-      localStorage.removeItem(this.#cacheCurrentKey);
-    }
+    if (this.cache) localStorage.removeItem(this.#cacheKey);
     return this.setLanguage(this.detectLanguage());
   }
 
-  // 一般用在 `onChange` 中
+  // 一般用在 `onChange` 中，子模块的语言来自主模块，不缓存
   setCache() {
-    if (this.#isMain) {
-      modules.forEach((i18n) => i18n.setCache());
-    }
-    localStorage.setItem(this.#cacheCurrentKey, this.currentLanguage);
-  }
-
-  createSubModule<K = Record<string, Msg>>(name: string, resources: Resources<K>) {
-    const module = new I18n<K>({
-      resources,
-      cachePrefix: `${this.cachePrefix}-${name}`,
-      currentLanguage: this.currentLanguage,
-      fallbackLanguage: this.fallbackLanguage,
-      cache: this.cache,
-    });
-    modules.add(module);
-    return module;
+    if (this.#isSub) return;
+    localStorage.setItem(this.#cacheKey, this.currentLanguage);
   }
 
   /**
+   * 子模块跟随主模块切换语言，可以按路由分割语言包
+   *
    * @example
    *
-   * html`
-   *  <gem-reflect>
-   *    <script type="${i18n.cachePrefix}">${JSON.stringify(i18n)}</script>
-   *  </gem-reflect>
-   * `
+   * const pageI18n = i18n.createSubModule('page', {
+   *   en: () => import('./en.json'),
+   *   zh: () => import('./zh.json'),
+   * });
    */
-  toJSON() {
-    return {
-      currentLanguage: this.currentLanguage,
-      currentLanguagePack: this.resources[this.currentLanguage],
-    };
+  createSubModule<K = Record<string, Msg>>(name: string, resources: Resources<K>) {
+    creatingSubModule = true;
+    try {
+      const module = new I18n<K>({
+        resources,
+        cachePrefix: `${this.cachePrefix}-${name}`,
+        currentLanguage: this.currentLanguage,
+        fallbackLanguage: this.fallbackLanguage,
+        cache: this.cache,
+      });
+      this.#subModules.add(module);
+      return module;
+    } finally {
+      creatingSubModule = false;
+    }
   }
 }

package/src/lib/decorators.ts

@@ -418,7 +418,8 @@ export type Emitter<T = any> = <_Listener = EmitterListener<T>>(
 
 /**
  * 定义一个事件发射器，类似 `HTMLElement.click`，
- * 调用时将同步发送一个和字段名称的烤串式格式的自定义事件
+ * 调用时将在微任务中发送一个和字段名称的烤串式格式的自定义事件，
+ * 避免同步触发时祖先元素还没挂载好（https://github.com/mantou132/gem/issues/203）
  *
  * @example
  * ```ts

package/src/lib/element.ts

@@ -13,11 +13,12 @@ export { createRef, mathml, svg, TemplateResult } from './lit-html';
 export * from './reactive';
 export { repeat } from './repeat';
 
+type HookExports = typeof reactiveExports & typeof decoratorsExports & typeof storeExports & typeof versionExports;
+
 declare global {
-  var __GEM_DEVTOOLS__HOOK__:
-    | (typeof reactiveExports & typeof decoratorsExports & typeof storeExports & typeof versionExports)
-    | Record<string, never>
-    | undefined;
+  /** devtools 注入的钩子，其他包可以扩展，例如 gem-ssr */
+  interface GemDevToolsHook extends HookExports {}
+  var __GEM_DEVTOOLS__HOOK__: GemDevToolsHook | Record<string, never> | undefined;
 }
 
 // 只记录第一次定义，往往是最外层 App