@psytask/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+type LooseObject = Record<string, any>;
+type Merge<T, U> = T extends any ? Omit<T, keyof U> & U : never;
+
+declare const symbol: typeof Symbol.dispose;
+/** {@link Disposable} event emitter, use {@link Set} to manage listeners */
+declare class EventEmitter<M extends LooseObject & {
+    dispose?: never;
+} = {}, EventMap extends {
+    dispose: null;
+} = M & {
+    dispose: null;
+}> implements Disposable {
+    readonly listeners: {
+        readonly [K in keyof EventMap]?: Set<(e: EventMap[K]) => void>;
+    };
+    [symbol](): void;
+    /** Add event listener */
+    on<K extends keyof EventMap>(type: K, listener: (evt: EventMap[K]) => void): this;
+    /** Remove event listener */
+    off<K extends keyof EventMap>(type: K, listener: (evt: EventMap[K]) => void): this;
+    /** Add one-time event listener, can not be removed manually */
+    once<K extends keyof EventMap>(type: K, listener: (evt: EventMap[K]) => void): this;
+    /** Emit event listeners */
+    emit<K extends keyof EventMap>(type: K, e: EventMap[K]): this;
+}
+
+declare const createShowInfo: () => {
+    start_time: number;
+    frame_times: number[];
+};
+type SceneShowInfo = ReturnType<typeof createShowInfo>;
+type ForbiddenSceneData = {
+    [K in keyof SceneShowInfo]?: never;
+};
+type SceneTimerCreator = (options: {
+    frame_ms: number;
+    duration?: number;
+    onStart: (time: number) => void;
+    onFrame: (time: number) => void;
+}) => {
+    promise: Promise<void>;
+    close: () => void;
+};
+type NodeLike = string | Node;
+/**
+ * Scene setup function, only called once when the scene is created.
+ *
+ * @param props - The reactive props to control the scene display
+ * @param ctx - The scene instance, can be used to manage lifecycle
+ * @see {@link Scene}
+ */
+type SceneSetup<P extends LooseObject = any, D extends LooseObject = LooseObject & ForbiddenSceneData> = (props: P, ctx: Scene<any>) => NodeLike | NodeLike[] | {
+    /** The node(s) appended to the root element of scene */
+    node: NodeLike | NodeLike[];
+    /** Data getter to get data from elements */
+    data: () => D;
+};
+type SceneShow<P extends LooseObject = any, D extends LooseObject = LooseObject & ForbiddenSceneData> = (patchProps?: Partial<P>) => Promise<Merge<D, SceneShowInfo>>;
+type GenericSceneSetup<P extends LooseObject = any, D extends LooseObject = LooseObject & ForbiddenSceneData> = SceneShow<P, D>;
+/**
+ * Provide type infer for generic setup function, do nothing in runtime.
+ *
+ * @example
+ *
+ * Support generic scene setup function
+ *
+ * ```ts
+ * using scene = new Scene(
+ *   generic(<T>(props: T) => ({ node: [], data: () => props })),
+ *   //...
+ * );
+ * const data = await scene.show({ text: 'hello' });
+ * data; // expect: { text: string }
+ * ```
+ */
+declare const generic: {
+    <P extends LooseObject, D extends LooseObject & ForbiddenSceneData = {}>(f: SceneSetup<P, D>): GenericSceneSetup<P, D>;
+};
+/** @ignore */
+type MaybeGenericSceneSetup = SceneSetup | GenericSceneSetup;
+/**
+ * Scene lifecycle and root element event name-value pairs.
+ *
+ * | name                  | trigger timing                                                                                           |
+ * | --------------------- | -------------------------------------------------------------------------------------------------------- |
+ * | scene:show            | the scene is shown                                                                                       |
+ * | scene:frame           | on each frame when the scene is shown                                                                    |
+ * | scene:close           | the scene is closed                                                                                      |
+ * | mouse:left            | the left mouse button is pressed                                                                         |
+ * | mouse:middle          | the middle mouse button is pressed                                                                       |
+ * | mouse:right           | the right mouse button is pressed                                                                        |
+ * | mouse:unknown         | an unknown mouse button is pressed                                                                       |
+ * | key:\<key\>           | a {@link https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values key} is pressed  |
+ * | \<HTMLElement-Event\> | an {@link https://developer.mozilla.org/docs/Web/API/HTMLElement#events html element event} is triggered |
+ */
+type SceneEventMap = HTMLElementEventMap & {
+    'scene:show': LooseObject;
+    'scene:frame': number;
+    'scene:close': null;
+} & {
+    [K in `mouse:${'left' | 'middle' | 'right' | 'unknown'}`]: MouseEvent;
+} & {
+    [K in `key:${string}`]: KeyboardEvent;
+};
+/** Scene options */
+type SceneOptions<T extends MaybeGenericSceneSetup> = {
+    /** Root element */
+    root: HTMLDivElement;
+    /** Frame duration in milliseconds */
+    frame_ms: number;
+    /** Default props */
+    defaultProps: Parameters<T>[0];
+    /** Scene duration in milliseconds */
+    duration?: number;
+    /** Close on specific {@link SceneEventMap events} */
+    close_on?: keyof SceneEventMap | (keyof SceneEventMap)[];
+    /** Whether to record frame times */
+    record_frame_times?: boolean;
+    /** Control display timing */
+    createTimer?: SceneTimerCreator;
+};
+declare class Scene<T extends MaybeGenericSceneSetup> extends EventEmitter<SceneEventMap> {
+    #private;
+    /** Root element */
+    readonly root: HTMLDivElement;
+    /**
+     * Show the scene and change props one-time
+     *
+     * @example
+     *
+     * Basic usage
+     *
+     * ```ts
+     * using scene = new Scene(
+     *   (props: { text: string }, ctx) => {
+     *     const node = document.createElement('div');
+     *     ctx.on('scene:show', (newProps) => {
+     *       node.textContent = newProps.text;
+     *     });
+     *     return node;
+     *   },
+     *   {
+     *     //...
+     *     defaultProps: { text: 'default' },
+     *   },
+     * );
+     * await scene.show({ text: 'new' }); // show `new`
+     * await scene.show(); // show `default`
+     * ```
+     *
+     * @function
+     */
+    show: T extends SceneSetup<infer P, infer D> ? SceneShow<P, D> : T;
+    /**
+     * @param setup - The {@link SceneSetup scene setup function}
+     * @param defaultOptions - Default {@link SceneOptions scene options}
+     */
+    constructor(setup: T, defaultOptions: SceneOptions<T>);
+    /**
+     * Override default options one-time
+     *
+     * @example
+     *
+     * Change duration temporarily
+     *
+     * ```ts
+     * using scene = new Scene(() => '', {
+     *   root: document.appendChild(document.createElement('div')),
+     *   frame_ms: 16.67,
+     *   defaultProps: {},
+     *   duration: 100,
+     * });
+     * await scene.config({ duration: 200 }).show(); // show 200ms
+     * await scene.show(); // show 100ms
+     * ```
+     */
+    config(patchOptions: {
+        [K in {
+            [K in keyof SceneOptions<T>]-?: undefined extends SceneOptions<T>[K] ? K : never;
+        }[keyof SceneOptions<T>]]?: SceneOptions<T>[K];
+    }): this;
+    /** Add a microtask to close the scene. It is useful when close in 'scene:show' */
+    close(): Promise<void>;
+}
+
+type EventType<T extends EventTarget, U = keyof T> = U extends `on${infer K}` ? K : never;
+/**
+ * Add event listener and return cleanup function
+ *
+ * @example
+ *
+ * Listen to window resize event
+ *
+ * ```ts
+ * const cleanup = on(window, 'resize', (e) => {});
+ * ```
+ */
+declare const on: <T extends EventTarget, K extends EventType<T>>(target: T, type: K, listener: (ev: `on${K}` extends infer P extends Extract<keyof T, string> ? T[P] & {} extends infer F extends (...args: any) => any ? Parameters<F>[0] : never : never) => void, options?: boolean | AddEventListenerOptions) => () => void;
+
+export { EventEmitter, Scene, generic, on };
+export type { MaybeGenericSceneSetup, NodeLike, SceneEventMap, SceneOptions, SceneSetup, SceneTimerCreator };

package/dist/index.js

@@ -0,0 +1,143 @@
+/** @psytask/core v1.0.0 cubxx MIT */
+
+// src/event-emitter.ts
+var symbol = Symbol.dispose ?? Symbol.for("Symbol.dispose");
+
+class EventEmitter {
+  listeners = {};
+  [symbol]() {
+    this.emit("dispose", null);
+  }
+  on(type, listener) {
+    (this.listeners[type] ??= new Set).add(listener);
+    return this;
+  }
+  off(type, listener) {
+    const listeners = this.listeners[type];
+    if (listeners) {
+      listeners.delete(listener);
+      listeners.size === 0 && delete this.listeners[type];
+    }
+    return this;
+  }
+  once(type, listener) {
+    const wrapper = (evt) => {
+      try {
+        listener(evt);
+      } finally {
+        this.off(type, wrapper);
+      }
+    };
+    this.on(type, wrapper);
+    return this;
+  }
+  emit(type, e) {
+    const listeners = this.listeners[type];
+    if (listeners)
+      for (const listener of [...listeners])
+        listener(e);
+    return this;
+  }
+}
+// ../../shared/utils.ts
+var ERR = (msg) => {
+  throw Error(msg);
+};
+var rAF = requestAnimationFrame;
+var array_normalize = (e) => Array.isArray(e) ? e : [e];
+
+// src/utils.ts
+var on = (target, type, listener, options) => (target.addEventListener(type, listener, options), () => target.removeEventListener(type, listener, options));
+
+// src/scene.ts
+var createShowInfo = () => ({ start_time: NaN, frame_times: [] });
+var createRAFTimer = (opts) => {
+  let start_time, close;
+  const frame = (last_time) => (opts.onFrame(last_time), typeof opts.duration === "number" && last_time - start_time >= opts.duration - opts.frame_ms * 1.5 ? close() : handle = rAF(frame));
+  let handle = rAF((last_time) => (opts.onStart(last_time), frame(start_time = last_time)));
+  return {
+    promise: new Promise((resolve) => close = () => (cancelAnimationFrame(handle), resolve())),
+    close
+  };
+};
+var generic = (f) => f;
+var mouseSuffixs = ["left", "middle", "right"];
+var prefix2type = {
+  scene: 0,
+  dispose: 0,
+  key: "keydown",
+  mouse: "mousedown"
+};
+
+class Scene extends EventEmitter {
+  root;
+  #data;
+  show = this.#show;
+  #options;
+  #defaultOptions;
+  #timer;
+  constructor(setup, defaultOptions) {
+    super();
+    const { root, defaultProps } = this.#defaultOptions = defaultOptions;
+    (this.root = root).tabIndex = -1;
+    const reset = () => {
+      root.style.transform = "scale(0)";
+      this.#options = defaultOptions;
+      this.#timer = undefined;
+    };
+    reset();
+    const metaOrNode = setup(defaultProps, this.on("scene:close", reset).on("dispose", () => root.remove()));
+    root.append(...array_normalize(typeof metaOrNode === "object" && "node" in metaOrNode ? (this.#data = metaOrNode.data, metaOrNode.node) : metaOrNode));
+  }
+  config(patchOptions) {
+    this.#options = { ...this.#defaultOptions, ...patchOptions };
+    return this;
+  }
+  async close() {
+    await 0;
+    this.#timer?.close();
+  }
+  async#show(patchProps) {
+    if (this.#timer)
+      ERR("Scene is showing");
+    const {
+      root,
+      frame_ms,
+      createTimer = createRAFTimer,
+      defaultProps,
+      duration,
+      close_on,
+      record_frame_times
+    } = this.#options;
+    this.emit("scene:show", { ...defaultProps, ...patchProps });
+    root.style.transform = "scale(1)";
+    root.focus();
+    if (typeof close_on !== "undefined") {
+      const close = () => this.close();
+      array_normalize(close_on).map((type) => this.on(type, close).once("scene:close", () => this.off(type, close)));
+    }
+    let hasMouseType = 0, hasKeyType = 0;
+    const cleanups = Object.keys(this.listeners).map((type) => {
+      const DOM_type = prefix2type[type.split(":", 1)[0]] ?? type;
+      return DOM_type === "keydown" ? !hasKeyType++ && on(root, DOM_type, (e) => this.emit(`key:${e.key}`, e).emit(DOM_type, e)) : DOM_type === "mousedown" ? !hasMouseType++ && on(root, DOM_type, (e) => this.emit(`mouse:${mouseSuffixs[e.button] ?? "unknown"}`, e).emit(DOM_type, e)) : DOM_type && on(root, DOM_type, (e) => this.emit(type, e));
+    });
+    this.once("scene:close", () => cleanups.map((fn) => fn && fn()));
+    const showInfo = createShowInfo();
+    await (this.#timer = createTimer({
+      frame_ms,
+      duration,
+      onStart: (time) => showInfo.start_time = time,
+      onFrame: (time) => {
+        record_frame_times && showInfo.frame_times.push(time);
+        this.emit("scene:frame", time);
+      }
+    })).promise;
+    return { ...this.emit("scene:close", null).#data?.(), ...showInfo };
+  }
+}
+export {
+  on,
+  generic,
+  Scene,
+  EventEmitter
+};

package/dist/index.min.js

@@ -0,0 +1,2 @@
+/** @psytask/core v1.0.0 cubxx MIT */
+var V=Symbol.dispose??Symbol.for("Symbol.dispose");class P{listeners={};[V](){this.emit("dispose",null)}on(T,c){return(this.listeners[T]??=new Set).add(c),this}off(T,c){let x=this.listeners[T];if(x)x.delete(c),x.size===0&&delete this.listeners[T];return this}once(T,c){let x=(k)=>{try{c(k)}finally{this.off(T,x)}};return this.on(T,x),this}emit(T,c){let x=this.listeners[T];if(x)for(let k of[...x])k(c);return this}}var A=(T)=>{throw Error(T)},r=requestAnimationFrame;var C=(T)=>Array.isArray(T)?T:[T];var E=(T,c,x,k)=>(T.addEventListener(c,x,k),()=>T.removeEventListener(c,x,k));var B=()=>({start_time:NaN,frame_times:[]}),F=(T)=>{let c,x,k=(b)=>(T.onFrame(b),typeof T.duration==="number"&&b-c>=T.duration-T.frame_ms*1.5?x():U=r(k)),U=r((b)=>(T.onStart(b),k(c=b)));return{promise:new Promise((b)=>x=()=>(cancelAnimationFrame(U),b())),close:x}},d=(T)=>T,G=["left","middle","right"],J={scene:0,dispose:0,key:"keydown",mouse:"mousedown"};class Q extends P{root;#c;show=this.#j;#x;#b;#T;constructor(T,c){super();let{root:x,defaultProps:k}=this.#b=c;(this.root=x).tabIndex=-1;let U=()=>{x.style.transform="scale(0)",this.#x=c,this.#T=void 0};U();let b=T(k,this.on("scene:close",U).on("dispose",()=>x.remove()));x.append(...C(typeof b==="object"&&"node"in b?(this.#c=b.data,b.node):b))}config(T){return this.#x={...this.#b,...T},this}async close(){await 0,this.#T?.close()}async#j(T){if(this.#T)A("Scene is showing");let{root:c,frame_ms:x,createTimer:k=F,defaultProps:U,duration:b,close_on:H,record_frame_times:L}=this.#x;if(this.emit("scene:show",{...U,...T}),c.style.transform="scale(1)",c.focus(),typeof H<"u"){let j=()=>this.close();C(H).map((K)=>this.on(K,j).once("scene:close",()=>this.off(K,j)))}let z=0,$=0,q=Object.keys(this.listeners).map((j)=>{let K=J[j.split(":",1)[0]]??j;return K==="keydown"?!$++&&E(c,K,(n)=>this.emit(`key:${n.key}`,n).emit(K,n)):K==="mousedown"?!z++&&E(c,K,(n)=>this.emit(`mouse:${G[n.button]??"unknown"}`,n).emit(K,n)):K&&E(c,K,(n)=>this.emit(j,n))});this.once("scene:close",()=>q.map((j)=>j&&j()));let g=B();return await(this.#T=k({frame_ms:x,duration:b,onStart:(j)=>g.start_time=j,onFrame:(j)=>{L&&g.frame_times.push(j),this.emit("scene:frame",j)}})).promise,{...this.emit("scene:close",null).#c?.(),...g}}}export{E as on,d as generic,Q as Scene,P as EventEmitter};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@psytask/core",
+  "version": "1.0.0",
+  "type": "module",
+  "author": "cubxx",
+  "license": "MIT",
+  "description": "Core for PsyTask",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}