@mantou/gem 2.1.0 → 2.2.0

package/src/lib/decorators.ts

@@ -1,5 +1,5 @@
-import type { createCSSSheet, Metadata, TemplateResult } from './element';
-import { GemElement, UpdateToken, createTemplate, RenderErrorEvent, render } from './element';
+import type { css, Metadata, TemplateResult } from './element';
+import { GemElement, UpdateToken, _createTemplate, _RenderErrorEvent, render } from './element';
 import { camelToKebabCase, PropProxyMap, GemError } from './utils';
 import type { Store } from './store';
 import * as elementExports from './element';
@@ -7,7 +7,7 @@ import * as decoratorsExports from './decorators';
 import * as storeExports from './store';
 import * as versionExports from './version';
 
-type GemElementPrototype = GemElement;
+type GemElementPrototype = GemElement & { '': never };
 type StaticField = Exclude<keyof Metadata, keyof ShadowRootInit | 'aria' | 'noBlocking' | 'penetrable'>;
 
 const { deleteProperty, getOwnPropertyDescriptor, defineProperty } = Reflect;
@@ -18,10 +18,8 @@ function pushStaticField(context: ClassFieldDecoratorContext | ClassDecoratorCon
   const metadata = context.metadata as Metadata;
   if (!getOwnPropertyDescriptor(metadata, field)) {
     // 继承基类
-    const current = new Set<unknown>(metadata[field]);
-    current.delete(member);
     defineProperty(metadata, field, {
-      value: [...current],
+      value: metadata[field]?.filter((e) => e !== member) || [],
     });
   }
 
@@ -96,10 +94,13 @@ function defineProp(
       if (event) {
         proxy[prop] = v?.[isEventHandleSymbol]
           ? v
-          : (detail: any, options: any) => {
+          : async (detail: any, options: any) => {
+              // 事件如果同步触发，则祖先元素可能还没有挂载好，其中就不能更新 state
+              // https://github.com/mantou132/gem/issues/203
+              await Promise.resolve();
               const evt = new CustomEvent(event, { ...options, ...eventOptions, detail });
               that.dispatchEvent(evt);
-              v(detail, options);
+              await v(detail, options);
             };
         (proxy[prop] as any)[isEventHandleSymbol] = true;
         // emitter 不触发元素更新
@@ -111,21 +112,35 @@ function defineProp(
   });
 }
 
+// https://github.com/tc39/proposal-decorators/issues/517
+const targetCache = new WeakMap<DecoratorMetadataObject, GemElementPrototype>();
+function getDecoratorTarget(element: GemElement, { metadata }: ClassFieldDecoratorContext) {
+  const target = targetCache.get(metadata);
+  if (target) return target;
+  let result = element as GemElementPrototype;
+  do {
+    result = getPrototypeOf(result);
+  } while (result.constructor[Symbol.metadata] !== metadata);
+  targetCache.set(metadata, result);
+  return result;
+}
+
 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 = getPrototypeOf(this);
+    const target = getDecoratorTarget(this, context);
     if (!target.hasOwnProperty(prop)) {
       pushStaticField(context, 'observedAttributes', attr); // 没有 observe 的效果
       defineProp(target, prop, { attr, attrType });
-      // 记录观察的 attribute
-      const attrMap = observedTargetAttributes.get(target) || new Map<string, string>();
-      attrMap.set(attr, prop);
-      observedTargetAttributes.set(target, attrMap);
     }
     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);
   });
   // 延时定义的元素需要继承原实例属性值
   return function (this: any, initValue: any) {
@@ -166,7 +181,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 = getPrototypeOf(this);
+    const target = getDecoratorTarget(this, context);
     if (!target.hasOwnProperty(prop)) {
       pushStaticField(context, 'observedProperties', prop);
       defineProp(target, prop);
@@ -214,14 +229,15 @@ export function memo<T extends GemElement, V = any, K = any[] | undefined>(
 }
 
 /**
- * 依赖 `GemElement.effect`
- * 方法执行在字段前面
+ * - 依赖 `GemElement.effect`
+ * - 方法执行在字段前面
+ * - 如果没有 oldValue，在为首次执行
  *
  * For example
  * ```ts
  *  class App extends GemElement {
  *    @effect(() => [])
- *    #fetchData() {
+ *    #fetchData(newValue, oldValue) {
  *      console.log('fetch')
  *    }
  *  }
@@ -273,7 +289,7 @@ export function template<T extends GemElement, V extends () => TemplateResult |
     { addInitializer, access }: ClassFieldDecoratorContext<T, V> | ClassMethodDecoratorContext<T, V>,
   ) {
     addInitializer(function (this: T) {
-      createTemplate(this, {
+      _createTemplate(this, {
         render: access.get(this).bind(this),
         condition: condition && (() => condition(this) as any),
       });
@@ -287,7 +303,7 @@ export function fallback<T extends GemElement, V extends (err: any) => TemplateR
     { addInitializer, access }: ClassFieldDecoratorContext<T, V> | ClassMethodDecoratorContext<T, V>,
   ) {
     addInitializer(function (this: T) {
-      this.addEventListener(RenderErrorEvent, ({ detail }: CustomEvent) => {
+      this.addEventListener(_RenderErrorEvent, ({ detail }: CustomEvent) => {
         render(access.get(this).apply(this, [detail]), this.internals.shadowRoot || this);
       });
     });
@@ -328,11 +344,11 @@ 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 = getPrototypeOf(this);
-    const prop = context.name as string;
+    const target = getDecoratorTarget(this, context);
     if (!target.hasOwnProperty(prop)) {
-      const attr = camelToKebabCase(prop);
       pushStaticField(context, 'definedCSSStates', attr);
       defineCSSState(target, prop, attr);
     }
@@ -394,7 +410,7 @@ export function part(_: undefined, context: ClassFieldDecoratorContext<any, stri
   };
 }
 
-export type Emitter<T = any> = (detail?: T, options?: Omit<CustomEventInit<unknown>, 'detail'>) => void;
+export type Emitter<T = any> = (detail?: T, options?: Omit<CustomEventInit<unknown>, 'detail'>) => Promise<void> | void;
 
 /**
  * 定义一个事件发射器，类似 `HTMLElement.click`，
@@ -408,28 +424,25 @@ export type Emitter<T = any> = (detail?: T, options?: Omit<CustomEventInit<unkno
  * ```
  */
 export function emitter<T extends GemElement>(_: undefined, context: ClassFieldDecoratorContext<T, Emitter>) {
-  context.addInitializer(function (this: T) {
-    defineEmitter(context, this, context.name as string);
-  });
+  defineEmitter(context);
 }
 export function globalemitter<T extends GemElement>(_: undefined, context: ClassFieldDecoratorContext<T, Emitter>) {
-  context.addInitializer(function (this: T) {
-    defineEmitter(context, this, context.name as string, { bubbles: true, composed: true });
-  });
+  defineEmitter(context, { bubbles: true, composed: true });
 }
-function defineEmitter(
+function defineEmitter<T extends GemElement>(
   context: ClassFieldDecoratorContext,
-  t: GemElement,
-  prop: string,
   eventOptions?: Omit<CustomEventInit<unknown>, 'detail'>,
 ) {
-  const target = getPrototypeOf(t);
-  if (!target.hasOwnProperty(prop)) {
-    const event = camelToKebabCase(prop);
-    pushStaticField(context, 'definedEvents', event);
-    defineProp(target, prop, { event, eventOptions });
-  }
-  clearField(t, prop);
+  const prop = context.name as string;
+  const event = camelToKebabCase(prop);
+  context.addInitializer(function (this: T) {
+    const target = getDecoratorTarget(this, context);
+    if (!target.hasOwnProperty(prop)) {
+      pushStaticField(context, 'definedEvents', event);
+      defineProp(target, prop, { event, eventOptions });
+    }
+    clearField(this, prop);
+  });
 }
 
 /**
@@ -441,7 +454,7 @@ function defineEmitter(
  *  class App extends GemElement {}
  * ```
  */
-export function adoptedStyle(sheet: ReturnType<typeof createCSSSheet>) {
+export function adoptedStyle(sheet: ReturnType<typeof css>) {
   return function (_: unknown, context: ClassDecoratorContext) {
     pushStaticField(context, 'adoptedStyleSheets', sheet);
   };

package/src/lib/directive.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import type { Disconnectable, Part } from './lit-html.js';
+
+export type {
+  AttributePart,
+  BooleanAttributePart,
+  ChildPart,
+  ElementPart,
+  EventPart,
+  Part,
+  PropertyPart,
+} from './lit-html.js';
+
+export interface DirectiveClass {
+  new (part: PartInfo): Directive;
+}
+
+/**
+ * This utility type extracts the signature of a directive class's render()
+ * method so we can use it for the type of the generated directive function.
+ */
+export type DirectiveParameters<C extends Directive> = Parameters<C['render']>;
+
+/**
+ * A generated directive function doesn't evaluate the directive, but just
+ * returns a DirectiveResult object that captures the arguments.
+ */
+export interface DirectiveResult<C extends DirectiveClass = DirectiveClass> {
+  /**
+   * This property needs to remain unminified.
+   * @internal
+   */
+  ['_$litDirective$']: C;
+  /** @internal */
+  values: DirectiveParameters<InstanceType<C>>;
+}
+
+export const PartType = {
+  ATTRIBUTE: 1,
+  CHILD: 2,
+  PROPERTY: 3,
+  BOOLEAN_ATTRIBUTE: 4,
+  EVENT: 5,
+  ELEMENT: 6,
+} as const;
+
+export type PartType = (typeof PartType)[keyof typeof PartType];
+
+export interface ChildPartInfo {
+  readonly type: typeof PartType.CHILD;
+}
+
+export interface AttributePartInfo {
+  readonly type:
+    | typeof PartType.ATTRIBUTE
+    | typeof PartType.PROPERTY
+    | typeof PartType.BOOLEAN_ATTRIBUTE
+    | typeof PartType.EVENT;
+  readonly strings?: ReadonlyArray<string>;
+  readonly name: string;
+  readonly tagName: string;
+}
+
+export interface ElementPartInfo {
+  readonly type: typeof PartType.ELEMENT;
+}
+
+/**
+ * Information about the part a directive is bound to.
+ *
+ * This is useful for checking that a directive is attached to a valid part,
+ * such as with directive that can only be used on attribute bindings.
+ */
+export type PartInfo = ChildPartInfo | AttributePartInfo | ElementPartInfo;
+
+/**
+ * Creates a user-facing directive function from a Directive class. This
+ * function has the same parameters as the directive's render() method.
+ */
+export const directive =
+  <C extends DirectiveClass>(c: C) =>
+  (...values: DirectiveParameters<InstanceType<C>>): DirectiveResult<C> => ({
+    // This property needs to remain unminified.
+    ['_$litDirective$']: c,
+    values,
+  });
+
+/**
+ * Base class for creating custom directives. Users should extend this class,
+ * implement `render` and/or `update`, and then pass their subclass to
+ * `directive`.
+ */
+export abstract class Directive implements Disconnectable {
+  //@internal
+  __part!: Part;
+  //@internal
+  __attributeIndex: number | undefined;
+  //@internal
+  __directive?: Directive;
+
+  //@internal
+  _$parent!: Disconnectable;
+
+  // These will only exist on the AsyncDirective subclass
+  //@internal
+  _$disconnectableChildren?: Set<Disconnectable>;
+  // This property needs to remain unminified.
+  //@internal
+  ['_$notifyDirectiveConnectionChanged']?(isConnected: boolean): void;
+
+  constructor(_partInfo: PartInfo) {}
+
+  // See comment in Disconnectable interface for why this is a getter
+  get _$isConnected() {
+    return this._$parent._$isConnected;
+  }
+
+  /** @internal */
+  _$initialize(part: Part, parent: Disconnectable, attributeIndex: number | undefined) {
+    this.__part = part;
+    this._$parent = parent;
+    this.__attributeIndex = attributeIndex;
+  }
+  /** @internal */
+  _$resolve(part: Part, props: Array<unknown>): unknown {
+    return this.update(part, props);
+  }
+
+  abstract render(...props: Array<unknown>): unknown;
+
+  update(_part: Part, props: Array<unknown>): unknown {
+    return this.render(...props);
+  }
+}

package/src/lib/element.ts

@@ -1,23 +1,14 @@
-import type { TemplateResult } from 'lit-html';
-import { html, render } from 'lit-html';
-
-import type { GemReflectElement } from '../elements/reflect';
-
+import { html, render } from './lit-html';
+import type { TemplateResult } from './lit-html';
 import type { Store } from './store';
 import { connect } from './store';
-import { LinkedList, addMicrotask, isArrayChange, addListener, randomStr, createUpdater } from './utils';
+import { LinkedList, addMicrotask, isArrayChange, addListener, randomStr, createUpdater, GemError, raw } from './utils';
 
-export { html, svg, render, directive, TemplateResult, SVGTemplateResult } from 'lit-html';
+export { directive } from './directive';
+export { repeat } from './repeat';
+export { html, svg, mathml, render, TemplateResult, createRef } from './lit-html';
 
 declare global {
-  // 用于 css 选择器选择元素，使用 RefObject 自动选择获取
-  // 必须使用 attr 赋值
-  /**
-   * @attr ref
-   */
-  interface HTMLElement {
-    ref: string;
-  }
   interface DOMStringMap {
     gemReflect?: '';
     gemStyle?: '';
@@ -35,13 +26,13 @@ defineProperty(Symbol, 'metadata', { value: Symbol.for('Symbol.metadata') });
 
 const execCallback = (fun: any) => typeof fun === 'function' && fun();
 
-// 跨多个 gem 工作
+// 读取构造样式表，跨多个 gem 工作
 export const SheetToken = Symbol.for('gem@sheetToken');
-// proto prop
+// 更新元素，跨多个 gem 工作
 export const UpdateToken = Symbol.for('gem@update');
 
 const BoundaryCSSState = 'gem-style-boundary';
-export const RenderErrorEvent = 'gem@render-error';
+export const _RenderErrorEvent = 'gem@render-error';
 
 // fix modal-factory type error
 const updateTokenAlias = UpdateToken;
@@ -49,40 +40,6 @@ const updateTokenAlias = UpdateToken;
 const rootStyleSheetInfo = new WeakMap<Document | ShadowRoot, Map<CSSStyleSheet, number>>();
 const rootUpdateFnMap = new WeakMap<Map<CSSStyleSheet, number>, () => void>();
 
-const getReflectTargets = (ele: ShadowRoot | GemElement) =>
-  [...ele.querySelectorAll<GemReflectElement>('[data-gem-reflect]')].map((e) => e.target);
-
-class RefObject<T = HTMLElement> {
-  refSelector: string;
-  ele: GemElement | ShadowRoot;
-  ref: string;
-
-  constructor(current: GemElement) {
-    const ref = `ref-${randomStr()}`;
-    this.refSelector = `[ref=${ref}]`;
-    this.ele = current.internals.shadowRoot || current;
-    this.ref = ref;
-  }
-  get element() {
-    for (const e of [this.ele, ...getReflectTargets(this.ele)]) {
-      // 在 LightDOM 中可能工作很慢？
-      const result = e.querySelector(this.refSelector);
-      if (result) return result as T;
-    }
-  }
-  get elements() {
-    return [this.ele, ...getReflectTargets(this.ele)]
-      .map((e) => [...e.querySelectorAll(this.refSelector)] as T[])
-      .flat();
-  }
-  toString() {
-    return this.ref;
-  }
-}
-
-/**必须使用在字段中，否则会读取到错误的实例 */
-export let createRef: <T>() => RefObject<T>;
-
 class GemCSSStyleSheet extends CSSStyleSheet {
   #ele?: HTMLStyleElement;
 
@@ -146,7 +103,7 @@ class GemCSSSheet {
     return sheet;
   }
 
-  // 一般用于主题更新，不支持 layer
+  // 一般用于主题更新
   updateStyle() {
     this.#used.forEach((scope, sheet) => {
       sheet.replaceSync(scope ? `${scope}{${this.#content}}` : this.#content);
@@ -160,14 +117,26 @@ export type Sheet<T> = { [P in keyof T]: P } & { [SheetToken]: GemCSSSheet };
  *
  * 创建 style sheet 用于 `@adoptedStyle`，不支持样式更新，只支持自定义 CSS 属性
  */
-export function createCSSSheet<T extends Record<string, string>>(media: string, rules: T | string): Sheet<T>;
-export function createCSSSheet<T extends Record<string, string>>(rules: T | string): Sheet<T>;
-export function createCSSSheet<T extends Record<string, string>>(
-  mediaOrRules: T | string,
-  rulesValue?: T | string,
+export function css<T extends Record<string, string>>(media: TemplateStringsArray, ...rest: any[]): Sheet<T>;
+export function css<T extends Record<string, string>>(media: string, rules: T | string): Sheet<T>;
+export function css<T extends Record<string, string>>(rules: T | string): Sheet<T>;
+export function css<T extends Record<string, string>>(
+  mediaOrRules: T | string | TemplateStringsArray,
+  ...rest: any[]
 ): Sheet<T> {
-  const media = rulesValue ? (mediaOrRules as string) : '';
-  const rules = rulesValue || mediaOrRules;
+  let media = '';
+  let rules: T | string = '';
+
+  const rulesValue = rest.at(0);
+  if (Array.isArray(mediaOrRules)) {
+    rules = raw(mediaOrRules as TemplateStringsArray, ...rest);
+  } else if (rulesValue !== undefined) {
+    media = mediaOrRules as string;
+    rules = rulesValue;
+  } else {
+    rules = mediaOrRules as string;
+  }
+
   const styleSheet = new GemCSSSheet(media);
   const sheet: any = { [SheetToken]: styleSheet };
   let style = '';
@@ -232,7 +201,7 @@ type EffectItem<T> = {
   fixed?: boolean; // 不需要清理，只会添加一次
   values?: T;
   getDep?: GetDepFun<T>;
-  preCallback?: () => void;
+  preCallback?: any;
 };
 
 function execEffectList(list?: EffectItem<any>[]) {
@@ -261,7 +230,20 @@ function clearEffect(list: EffectItem<any>[]) {
 type Render = () => TemplateResult | null | undefined;
 type RenderItem = { render: Render; condition?: () => boolean };
 
-export let createTemplate: (ele: GemElement, item: RenderItem) => void;
+const nullTemplate = html`
+  <style>
+    :host {
+      display: none !important;
+    }
+    @scope {
+      :scope {
+        display: none !important;
+      }
+    }
+  </style>
+`;
+
+export let _createTemplate: (ele: GemElement, item: RenderItem) => void;
 
 export type Metadata = Partial<ShadowRootInit> & {
   /** 内容可被外部样式化 */
@@ -318,30 +300,33 @@ export abstract class GemElement extends HTMLElement {
   #isAppendReason?: boolean;
   #isMounted?: boolean;
   // not in constructor 的近似值
-  #isConnected?: boolean;
+  #notInCons?: boolean;
   #rendering?: boolean;
-  #clearStyle?: any;
+  #clearStyle?: (() => void) | undefined;
 
   [updateTokenAlias]() {
     // 避免 `connectedCallback` 中的 property 赋值造成多余更新
-    if (this.#isMounted) {
-      addMicrotask(this.#update);
-    }
+    if (this.#isMounted) addMicrotask(this.#update);
   }
 
   static {
     createState = <T>(initState: T) => {
       const ele = currentConstructGemElement;
       const state = createUpdater(initState, (payload) => {
+        const effect = ele.#effectList.at(0);
+        // https://github.com/mantou132/gem/issues/203
+        if (ele.#isMounted && effect && !effect.initialized) {
+          throw new GemError(`Do't set state sync before insert the DOM`);
+        }
         assign(state, payload);
         // 避免无限刷新
-        if (!ele.#rendering) addMicrotask(ele.#update);
+        // 挂载前 set state 不应该触发更新
+        if (!ele.#rendering && ele.#isMounted) addMicrotask(ele.#update);
       });
       ele.#internals.stateList.push(state);
       return state;
     };
-    createRef = () => new RefObject(currentConstructGemElement);
-    createTemplate = (ele, item) => ele.#renderList.push(item);
+    _createTemplate = (ele, item) => ele.#renderList.push(item);
   }
 
   constructor() {
@@ -385,7 +370,8 @@ export abstract class GemElement extends HTMLElement {
   }
 
   get #renderItem() {
-    return this.#renderList.find((e) => !e.condition || e.condition());
+    // 从末尾开始寻找，允许被覆盖
+    return this.#renderList.findLast((e) => !e.condition || e.condition());
   }
 
   get internals() {
@@ -405,9 +391,10 @@ export abstract class GemElement extends HTMLElement {
 
   /**
    * - 条件渲染
-   * - 不提供 `render` 时显示子内容
-   * - 返回 `null` 时渲染空的子内容
+   * - 没有 `render` 时显示子内容
    * - 返回 `undefined` 时不会更新现有内容
+   * - 返回 `null` 时渲染空内容
+   * - 返回 html`` 时渲染空的子内容
    * */
   #render = (item?: RenderItem) => {
     try {
@@ -417,9 +404,10 @@ export abstract class GemElement extends HTMLElement {
       const temp = item ? item.render() : isLight ? undefined : html`<slot></slot>`;
       this.#rendering = false;
       if (temp === undefined) return;
-      render(temp, this.#renderRoot);
+      render(temp === null ? nullTemplate : temp, this.#renderRoot);
     } catch (err) {
-      this.dispatchEvent(new CustomEvent(RenderErrorEvent, { bubbles: true, composed: true, detail: err }));
+      this.dispatchEvent(new CustomEvent(_RenderErrorEvent, { bubbles: true, composed: true, detail: err }));
+      throw err;
     }
   };
 
@@ -493,8 +481,12 @@ export abstract class GemElement extends HTMLElement {
   #connectedCallback = async () => {
     if (this.#isAppendReason) {
       this.#isAppendReason = false;
+      // https://github.com/mantou132/gem/issues/202
+      this.#clearStyle?.();
+      this.#clearStyle = this.#prepareStyle();
       return;
     }
+    this.#notInCons = true;
     this.#compat();
 
     const { observedStores, mode, penetrable } = this.#metadata;
@@ -503,7 +495,6 @@ export abstract class GemElement extends HTMLElement {
     // 如果渲染内容需要应用外部样式，需要手动 `delete` 边界
     if (!mode && this.#renderList.length && !penetrable) this.#internals.states.add(BoundaryCSSState);
 
-    this.#isConnected = true;
     this.#disconnectStore = observedStores?.map((store) => connect(store, this.#update));
     this.#render(this.#renderItem);
     this.#isMounted = true;
@@ -553,7 +544,7 @@ export abstract class GemElement extends HTMLElement {
     // 是否要异步执行回调？
     this.#effectList = clearEffect(this.#effectList);
     this.#memoList = clearEffect(this.#memoList);
-    execCallback(this.#clearStyle);
+    this.#clearStyle?.();
     return GemElement.#final;
   }
 
@@ -576,7 +567,7 @@ export abstract class GemElement extends HTMLElement {
       callback,
       getDep,
       initialized: this.#isMounted,
-      fixed: !this.#isConnected,
+      fixed: !this.#notInCons,
     };
     // 已挂载时立即执行副作用，未挂载时等挂载后执行
     if (this.#isMounted) {
@@ -607,7 +598,7 @@ export abstract class GemElement extends HTMLElement {
     this.#memoList.push({
       callback,
       getDep,
-      fixed: !this.#isConnected,
+      fixed: !this.#notInCons,
     });
   };