@mantou/gem 1.7.10 → 1.7.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantou/gem",
-  "version": "1.7.10",
+  "version": "1.7.12",
   "description": "💎 使用自定义元素的轻量级 WebApp 开发框架",
   "keywords": [
     "frontend",
@@ -30,7 +30,8 @@
   ],
   "typings": "index.d.ts",
   "scripts": {
-    "docs": "gem-book docs",
+    "docs": "GEM_BOOK_REPLACE=true gem-book docs",
+    "docs:remote": "yarn docs",
     "build:docs": "yarn docs --build",
     "build:module": "tsc -p tsconfig.build.json",
     "build:lib": "vite build",
@@ -43,13 +44,13 @@
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4-fix.0",
-    "@gemjs/config": "^1.6.12",
+    "@gemjs/config": "^1.6.14",
     "@open-wc/testing": "^2.5.33",
     "@web/dev-server-esbuild": "^0.2.16",
     "@web/test-runner": "^0.13.22",
     "rimraf": "^3.0.2",
-    "typescript": "^5.3.2",
-    "vite": "^2.7.13"
+    "typescript": "^5.4.3",
+    "vite": "^4.5.2"
   },
   "author": "mantou132",
   "license": "MIT",

package/src/elements/base/gesture.ts

@@ -46,11 +46,9 @@ function angleAB(
 /**
  * 块级元素，如果要设置成 `contents`，则内容块要设置 `touch-action: none`
  * https://javascript.info/pointer-events#event-pointercancel
- *
  * 在移动端上，必须设置 `touch-action` 以允许滚动等原生动作
  *
- * 为什么空白区域会自动触发 `pointercancel`?
- *
+ * @customElement gem-gesture
  * @event pan
  * @event pinch
  * @event rotate
@@ -76,7 +74,9 @@ export class GemGestureElement extends GemElement {
     this.addEventListener('pointermove', this.#onMoveSet);
     this.addEventListener('pointerup', this.#onEnd);
     this.addEventListener('pointerleave', this.#onEnd); // 有时候 up 没有触发？
+    // 为什么空白区域会自动触发 `pointercancel`?
     this.addEventListener('pointercancel', this.#onEnd);
+
     this.addEventListener('dragstart', (evt) => evt.preventDefault());
   }
 

package/src/elements/base/link.ts

@@ -10,6 +10,7 @@ function isExternal(path: string) {
 }
 
 /**
+ * @customElement gem-link
  * @attr href
  * @attr target
  * @attr doc-title
@@ -171,6 +172,7 @@ export class GemLinkElement extends GemElement {
 }
 
 /**
+ * @customElement gem-active-link
  * @attr pattern
  * @state active
  */

package/src/elements/base/reflect.ts

@@ -7,7 +7,7 @@
  * 比如 duoyun-ui 文档站加载示例元素时把 GemReflectElement 渲染的元素清除
  */
 import { GemElement } from '../../lib/element';
-import { property } from '../../lib/decorators';
+import { attribute, property } from '../../lib/decorators';
 
 const START = 'gem-reflect-start';
 const END = 'gem-reflect-end';
@@ -25,9 +25,18 @@ const getReflectFragment = (startNode: Comment) => {
   return result;
 };
 
+/**
+ * @customElement gem-reflect
+ */
 export class GemReflectElement extends GemElement {
+  @attribute method: 'prepend' | 'append';
+
   @property target: HTMLElement = document.head;
 
+  get #method() {
+    return this.method || 'append';
+  }
+
   constructor() {
     super({ isLight: true });
 
@@ -45,11 +54,14 @@ export class GemReflectElement extends GemElement {
 
     this.effect(
       () => {
-        if (!childNodes) {
-          [startNode, ...this.childNodes, endNode].forEach((node) => this.target.append(node));
-        } else {
-          childNodes.forEach((node) => this.target.append(node));
-        }
+        (childNodes || [startNode, ...this.childNodes, endNode]).forEach((node, index, arr) => {
+          const prev = arr[index - 1];
+          if (prev) {
+            prev.after(node);
+          } else {
+            this.target[this.#method](node);
+          }
+        });
         return () => {
           childNodes = getReflectFragment(startNode);
           childNodes.forEach((node) => node.remove());

package/src/elements/base/route.ts

@@ -72,13 +72,17 @@ export interface RouteItem<T = unknown> {
   pattern: string;
   redirect?: string;
   content?: TemplateResult;
-  getContent?: (params: Params) => TemplateResult | Promise<TemplateResult>;
+  // 返回 `undefined` 意味着不会执行 `render`， 支持 React 等组件挂载到 `<gem-route>` 元素下
+  getContent?: (
+    params: Params,
+    renderRoot: DocumentFragment | GemLightRouteElement,
+  ) => TemplateResult | Promise<TemplateResult> | undefined | Promise<undefined>;
   title?: string;
   // 用来传递数据
   data?: T;
 }
 
-export type RoutesObject = Record<string, RouteItem>;
+export type RoutesObject<T = unknown> = Record<string, RouteItem<T>>;
 
 // params 中的成员不会验证
 export interface RouteOptions extends Omit<UpdateHistoryParams, 'path'> {
@@ -88,7 +92,10 @@ export interface RouteOptions extends Omit<UpdateHistoryParams, 'path'> {
 // 从路由创建路径
 // 不包含 basePath
 export function createPath(route: RouteItem, options?: RouteOptions) {
-  let path = route.pattern;
+  // /a/* /a/:0
+  // /a/*/:b/* /a/:0/:b/:1
+  let i = 0;
+  let path = route.pattern.replaceAll('*', () => `:${i++}`);
   const params = options?.params;
   if (params) {
     Object.keys(params).forEach((key) => {
@@ -111,19 +118,22 @@ interface ConstructorOptions {
   routes?: RouteItem[] | RoutesObject;
 }
 
+const INIT_CONTENT = html``;
+
 type State = {
   content?: TemplateResult;
 };
 
 export type RouteTrigger = {
   store: Store<any>;
-  replace: (arg: { path: string }) => void;
+  replace: (arg: UpdateHistoryParams) => void;
   getParams: () => { path: string; query?: string | QueryString; hash?: string };
 };
 
 const scrollPositionMap = new Map<string, number>();
 
 /**
+ * @customElement gem-route
  * @attr inert 暂停路由更新
  * @fires routechange
  * @fires error
@@ -158,7 +168,7 @@ export class GemRouteElement extends GemElement<State> {
   /**当前匹配的路由的 params */
   currentParams: Params = {};
 
-  #lastLoader?: Promise<TemplateResult>;
+  #lastLoader?: Promise<TemplateResult | undefined>;
 
   /**不要多个 `<gem-route>` 共享，因为那样会导致后面的元素卸载前触发更新 */
   static createLocationStore = () => {
@@ -193,11 +203,11 @@ export class GemRouteElement extends GemElement<State> {
 
   constructor({ isLight, routes }: ConstructorOptions = {}) {
     super({ isLight });
-    this.routes = routes;
+    this.routes = this.routes || routes;
   }
 
   state: State = {
-    content: undefined,
+    content: INIT_CONTENT,
   };
 
   #updateLocationStore = () => {
@@ -282,7 +292,12 @@ export class GemRouteElement extends GemElement<State> {
 
   render() {
     const { content } = this.state;
-    if (!this.shadowRoot) return html`${content}`;
+    if (content === undefined) return;
+
+    if (!this.shadowRoot) {
+      if (content === INIT_CONTENT) return;
+      return html`${content}`;
+    }
 
     return html`
       <style>
@@ -291,23 +306,26 @@ export class GemRouteElement extends GemElement<State> {
           display: contents;
         }
       </style>
-      ${content ?? html`<slot></slot>`}
+      ${content === INIT_CONTENT ? html`<slot></slot>` : content}
     `;
   }
 
   update = () => {
-    const { route, params = {} } = GemRouteElement.findRoute(this.routes, this.trigger.getParams().path);
+    const { path, hash, query } = this.trigger.getParams();
+    const { route, params = {} } = GemRouteElement.findRoute(this.routes, path);
     const { redirect, content, getContent } = route || {};
     if (redirect) {
       this.trigger.replace({
         path: createPath({ pattern: redirect }, { params }),
+        query,
+        hash,
       });
       return;
     }
     if (this.trigger === history) {
       updateStore(titleStore, { title: route?.title });
     }
-    const contentOrLoader = content || getContent?.(params);
+    const contentOrLoader = content || getContent?.(params, this.shadowRoot || this);
     this.loading(route);
     if (contentOrLoader instanceof Promise) {
       this.#lastLoader = contentOrLoader;
@@ -325,6 +343,9 @@ export class GemRouteElement extends GemElement<State> {
   };
 }
 
+/**
+ * @customElement gem-light-route
+ */
 export class GemLightRouteElement extends GemRouteElement {
   constructor(options: ConstructorOptions = {}) {
     super({ ...options, isLight: true });

package/src/elements/base/title.ts

@@ -43,7 +43,7 @@ export const PREFIX = `${defaultTitle} | `;
 export const SUFFIX = ` - ${defaultTitle}`;
 
 /**
- * 映射到 `document.title`
+ * @customElement gem-title
  * @attr prefix
  * @attr suffix
  */

package/src/elements/base/unsafe.ts

@@ -2,8 +2,7 @@ import { GemElement } from '../../lib/element';
 import { attribute } from '../../lib/decorators';
 
 /**
- * 直接写会被解释成固定属性，需要使用变量赋值
- *
+ * @customElement gem-unsafe
  * @attr content
  * @attr contentcss
  */

package/src/elements/base/use.ts

@@ -6,9 +6,9 @@ const eleCache = new Map<string, HTMLTemplateElement>();
  * svg 中的 `<use>` 不能穿透 ShadowDOM,
  * 此元素用来模拟 `<use>`,
  * 由于是复制元素，所以不能像 `<use>` 一样自动更新
- *
  * slot 支持为 icon 添加效果，如涟漪，徽章
  *
+ * @customElement gem-use
  * @attr selector
  */
 export class GemUseElement extends GemElement {

package/src/helper/i18n.ts

@@ -74,10 +74,8 @@ export class I18n<T = Record<string, Msg>> implements RouteTrigger {
 
   store: Store<any>;
 
-  replace = ({ path }: { path: string }) => {
-    this.setLanguage(path);
-  };
-
+  // 兼容 `<gem-route>`
+  replace = ({ path }: { path: string }) => this.setLanguage(path);
   getParams = () => ({ path: this.currentLanguage });
 
   get #cacheCurrentKey() {

package/src/helper/request.ts

@@ -1,60 +1,129 @@
-export const defaultReqInit: RequestInit = {
-  headers: {
-    'Content-Type': 'application/json',
-  },
-};
-
-export async function request<T>(uri: string, options: RequestInit = {}): Promise<T> {
-  const res = await fetch(uri, {
-    ...defaultReqInit,
-    ...options,
-  });
-  if (res.status === 0) throw new Error('Request fail');
-  if (res.status >= 500) throw new Error(res.statusText);
-  try {
-    const data = await res.json();
-    if (res.status >= 400) throw new (Error as any)(data?.message || res.statusText, { cause: data });
-    return data;
-  } catch {
-    throw new Error('Server error');
-  }
-}
+import { GemError } from '../lib/utils';
 
 type ReqBody = Record<string, unknown> | BodyInit;
+type ReqParams = Record<string, string | number>;
 const TypedArray = Object.getPrototypeOf(Object.getPrototypeOf(new Int8Array())).constructor;
 
-function serializationBody(body?: ReqBody): BodyInit | undefined {
-  if (
-    body instanceof FormData ||
-    body instanceof Blob ||
-    body instanceof TypedArray ||
-    body instanceof URLSearchParams ||
-    body instanceof ReadableStream ||
-    body instanceof ArrayBuffer
-  ) {
-    return body as BodyInit;
-  }
-  if (typeof body === 'object') {
-    return JSON.stringify(body);
-  }
-  return body;
-}
+type Options = {
+  origin?: string;
+  base?: string;
+  // only for get/del/put/post
+  appendHeaders?: (input?: any) => HeadersInit;
+  transformInput?: (input?: any) => any;
+  transformOutput?: (output: any, req: Request) => any;
+} & RequestInit;
 
-function serializationUrl(url: string, params?: Record<string, string | number>) {
-  const { origin, pathname, search } = new URL(url, location.origin);
-  const query = new URLSearchParams(params as Record<string, string>).toString();
-  return `${origin}${pathname}${search ? `${search}&` : query ? '?' : ''}${query}`;
-}
+function initRequest(options: Options = {}) {
+  const {
+    origin = location.origin,
+    base = '',
+    appendHeaders = () => ({}),
+    transformInput = (p?: any) => p,
+    transformOutput = (p?: any) => p,
+    ...reqInit
+  } = options;
 
-export function get<T>(url: string, params?: Record<string, string | number>) {
-  return request<T>(serializationUrl(url, params), { method: 'GET' });
-}
-export function del<T>(url: string, params?: Record<string, string | number>) {
-  return request<T>(serializationUrl(url, params), { method: 'DELETE' });
-}
-export function put<T>(url: string, body?: ReqBody) {
-  return request<T>(url, { method: 'PUT', body: serializationBody(body) });
-}
-export function post<T>(url: string, body?: ReqBody) {
-  return request<T>(url, { method: 'POST', body: serializationBody(body) });
+  const serializationBody = (body?: ReqBody): BodyInit | undefined => {
+    if (
+      body instanceof FormData ||
+      body instanceof Blob ||
+      body instanceof TypedArray ||
+      body instanceof URLSearchParams ||
+      body instanceof ReadableStream ||
+      body instanceof ArrayBuffer
+    ) {
+      return body as BodyInit;
+    }
+    if (typeof body === 'object') {
+      return JSON.stringify(body);
+    }
+    return body;
+  };
+
+  const serializationUrl = (path: string, params?: ReqParams) => {
+    if (new URL(path, location.origin).pathname !== path) {
+      throw new GemError('`path` format is incorrect');
+    }
+    const query = new URLSearchParams(params as Record<string, string>).toString();
+    return `${origin}${base}${path}${query ? '?' : ''}${query}`;
+  };
+
+  const serializationHeaders = (headers?: HeadersInit) => {
+    if (!headers) return {};
+    // auto `toLowerCase`
+    if (headers instanceof Headers) return Object.fromEntries(headers);
+    const entries = Array.isArray(headers) ? headers : Object.entries(headers);
+    return Object.fromEntries(entries.map(([key, value]) => [key.toLowerCase(), value]));
+  };
+
+  const request = async <T>(uri: string, reqOptions: RequestInit = {}): Promise<T> => {
+    const req = new Request(uri, {
+      ...reqInit,
+      ...reqOptions,
+      headers: new Headers({
+        'content-type': 'application/json',
+        ...serializationHeaders(reqInit.headers),
+        ...serializationHeaders(reqOptions.headers),
+      }),
+    });
+    const res = await fetch(req);
+
+    if (res.status === 0) throw new Error('Request fail');
+    if (res.status >= 500) throw new Error(res.statusText);
+
+    const contentType = req.headers.get('content-type')!;
+    const isClientError = res.status >= 400;
+    try {
+      let data: any;
+      if (contentType.includes('json')) {
+        data = await res.json();
+      } else if (contentType.includes('octet-stream')) {
+        data = await res.arrayBuffer();
+      } else {
+        data = await res.text();
+      }
+      if (isClientError) throw new (Error as any)(res.statusText, { cause: data });
+      return transformOutput(data, req);
+    } catch {
+      throw new Error('Parse error');
+    }
+  };
+
+  return {
+    request,
+    get<T>(path: string, params?: ReqParams) {
+      const i = transformInput(params);
+      return request<T>(serializationUrl(path, i), {
+        method: 'GET',
+        headers: appendHeaders(i),
+      });
+    },
+    del<T>(path: string, params?: ReqParams) {
+      const i = transformInput(params);
+      return request<T>(serializationUrl(path, i), {
+        method: 'DELETE',
+        headers: appendHeaders(i),
+      });
+    },
+    put<T>(path: string, body?: ReqBody) {
+      const i = transformInput(body);
+      return request<T>(serializationUrl(path), {
+        method: 'PUT',
+        headers: appendHeaders(i),
+        body: serializationBody(i),
+      });
+    },
+    post<T>(path: string, body?: ReqBody) {
+      const i = transformInput(body);
+      return request<T>(serializationUrl(path), {
+        method: 'POST',
+        headers: appendHeaders(i),
+        body: serializationBody(i),
+      });
+    },
+  };
 }
+
+const { request, del, get, post, put } = initRequest();
+
+export { initRequest, request, del, get, post, put };

package/src/lib/decorators.ts

@@ -19,7 +19,7 @@ function pushStaticField(target: GemElementPrototype, field: StaticField, member
   (cls[field] as any)[isSet ? 'add' : 'push'](member);
 }
 
-export type RefObject<T = HTMLElement> = { ref: string; element: T | undefined };
+export type RefObject<T = HTMLElement> = { ref: string; element: T | undefined; elements: T[] };
 
 /**
  * 引用元素，只有第一个标记 ref 的元素有效

package/src/lib/element.ts

@@ -419,22 +419,17 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
 
   closestElement<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K] | null;
   closestElement<K extends abstract new (...args: any) => any>(constructor: K): InstanceType<K> | null;
-  closestElement<K extends abstract new (...args: any) => any>(constructorOrTag: K | string): Element | null {
+  closestElement<K extends abstract new (...args: any) => any>(constructorOrTag: K | string) {
     const isConstructor = typeof constructorOrTag === 'function';
     const tagName = typeof constructorOrTag === 'string' && constructorOrTag.toUpperCase();
-    const getRootElement = (ele: Element): Element | null => {
-      const rootEle = ele.parentElement || (ele.getRootNode() as ShadowRoot).host;
-      if (!rootEle) return null;
-      if (isConstructor) {
-        if (rootEle.constructor === constructorOrTag) {
-          return rootEle;
-        }
-      } else if (rootEle.tagName === tagName) {
-        return rootEle;
-      }
-      return getRootElement(rootEle);
-    };
-    return getRootElement(this);
+    const is = (ele: Element) => (isConstructor ? ele.constructor === constructorOrTag : ele.tagName === tagName);
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let node: Element | null = this;
+    while (node) {
+      if (is(node)) break;
+      node = node.parentElement || (node.getRootNode() as ShadowRoot).host;
+    }
+    return node;
   }
 
   /**
@@ -572,7 +567,11 @@ export function defineProperty(
   });
 }
 
+const getReflectTargets = (ele: ShadowRoot | GemElement) =>
+  [...ele.querySelectorAll<GemReflectElement>('[data-gem-reflect]')].map((e) => e.target);
+
 export function defineRef(target: GemElement, prop: string, ref: string) {
+  const refSelector = `[ref=${ref}]`;
   Object.defineProperty(target, prop, {
     configurable: true,
     get() {
@@ -586,12 +585,14 @@ export function defineRef(target: GemElement, prop: string, ref: string) {
             return ref;
           },
           get element() {
-            const gemReflects = [...ele.querySelectorAll<GemReflectElement>('[data-gem-reflect]')].map((e) => e.target);
-            for (const e of [ele, ...gemReflects]) {
-              const result = e.querySelector(`[ref=${ref}]`);
+            for (const e of [ele, ...getReflectTargets(ele)]) {
+              const result = e.querySelector(refSelector);
               if (result) return result;
             }
           },
+          get elements() {
+            return [ele, ...getReflectTargets(ele)].map((e) => [...e.querySelectorAll(refSelector)]).flat();
+          },
         };
         proxy[prop] = refobject;
       }

package/src/lib/store.ts

@@ -28,7 +28,9 @@ export function useStore<T extends NonPrimitive>(originStore: T) {
 export function connect<T extends NonPrimitive>(store: Store<T>, func: () => void) {
   const listeners = StoreListenerMap.get(store);
   listeners?.add(func);
-  return () => listeners?.delete(func);
+  return () => {
+    listeners?.delete(func);
+  };
 }
 
 export function disconnect<T extends NonPrimitive>(store: Store<T>, func: () => void) {