@mantou/gem 2.2.15 → 2.3.1

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/helper/theme.ts

@@ -26,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 异步更新
@@ -75,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;
 }
@@ -94,6 +100,7 @@ export function createOverrideTheme<T extends Record<string, unknown>>(theme: Th
 
 /**
  * 返回一个主题对象，但同时又是一个装饰器函数，用来装饰一个主题更新函数
+ * 所有实例共享变量名，`key` 同 `createScopedTheme`
  *
  * @example
  * ```ts
@@ -104,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,

package/src/lib/decorators.ts

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