ranuts 0.2.0-alpha.1 → 0.3.0-alpha.1

package/dist/src/utils/bom.d.ts

@@ -1,11 +1,12 @@
+import { noop } from '@/utils/noop';
 /**
- * @description: 覆盖浏览器的后退事件
+ * @description: Override the browser's back-button behaviour
  * @param {*} callback
  * @return {*}
  */
-export declare const retain: (callback?: () => void) => void;
+export declare const retain: (callback?: typeof noop) => void;
 /**
- * @description: 获取指定的 cookie
+ * @description: Read a named cookie
  * @param {string} objName
  * @return {*}
  */
@@ -26,7 +27,7 @@ export interface BaseReturn {
     message?: string;
 }
 /**
- * @description: url 转 arrayBuffer
+ * @description: Fetch a URL as an ArrayBuffer
  * @param {string} src
  * @param {RequestUrlToArraybufferOption} options
  * @return {*}
@@ -40,43 +41,84 @@ export interface Context {
     oBackingStorePixelRatio: number;
 }
 /**
- * @description: 获取分辨率
+ * @description: Get the device pixel ratio
  * @param {CanvasRenderingContext2D} context
  * @return {*}
  */
 export declare const getPixelRatio: (context: CanvasRenderingContext2D & Partial<Context>) => number;
 export declare const createObjectURL: (src: Blob | ArrayBuffer | Response) => Promise<string>;
 /**
- * @description: 计算每毫秒的帧率，每秒的帧率需要乘 1000
+ * @description: Frames per millisecond; multiply by 1000 for frames per second
  * @return {*}
  */
 export declare const getFrame: (n?: number) => Promise<number>;
 /**
- * @description: Gets the current environment configuration
- * @return {string}
- */
-export declare const getHost: (env?: string) => string | undefined;
-/**
- * @description: 将 url 上的字符串转换成对象
- * @param {string} url
- * @param {*} string
- * @return {*}
+ * @description: Parse a URL's query string into an object. Defaults to the current
+ * `window.location.href`, so it returns `{}` under SSR unless a URL is passed.
+ *
+ * A **bare flag keeps its place** as an empty string: `?embed` and `?embed=` both yield
+ * `{ embed: '' }`. The previous implementation dropped any parameter without a value,
+ * which made `?readonly` and `?embed` — the usual way to write a boolean flag —
+ * indistinguishable from the parameter being absent. Use [`queryFlag`](#queryflag) to read
+ * such a flag as a boolean.
+ *
+ * `+` is decoded as a space and a value containing `=` is preserved (only the first `=`
+ * splits), matching `URLSearchParams`.
+ *
+ * @param {string} url full URL or query string; defaults to the current location
+ * @return {Record<string, string>} parameters; `{}` when there are none
+ * @example
+ * ```ts
+ * getAllQueryString('https://x.dev/a?embed&lang=zh-CN&next=/a%3Fb%3D1');
+ * // { embed: '', lang: 'zh-CN', next: '/a?b=1' }
+ * ```
  */
 export declare const getAllQueryString: (url?: string) => Record<string, string>;
 /**
- * @description: 将 url 上的字符串转换成对象
- * @param {string} url
- * @param {*} string
- * @return {*}
+ * @description: Alias of [`getAllQueryString`](#getallquerystring). The two used to be
+ * byte-identical copies of the same body; this one now forwards so a fix lands in both.
+ * @param {string} url full URL or query string; defaults to the current location
+ * @return {Record<string, string>}
  */
 export declare const getQuery: (url?: string) => Record<string, string>;
 /**
- * @description: 将一个对象转换成 querystring，拼接到 url 后面
+ * @description: Read a query parameter as a boolean flag. True for `?k`, `?k=`, `?k=1` and
+ * `?k=true` (case-insensitive); false for anything else, including an absent parameter and
+ * an explicit `?k=false`.
+ *
+ * This is the URL spelling of a boolean: `?embed`, `?readonly` and `?debug` are all written
+ * without a value most of the time, so a plain `getQuery(url).embed` check is wrong for the
+ * most common form.
+ *
+ * @param {string} key parameter name
+ * @param {string} url full URL or query string; defaults to the current location
+ * @return {boolean}
+ * @example
+ * ```ts
+ * queryFlag('embed', '?embed');        // true
+ * queryFlag('embed', '?embed=1');      // true
+ * queryFlag('embed', '?embed=false');  // false
+ * queryFlag('embed', '?lang=en');      // false
+ * ```
+ */
+export declare const queryFlag: (key: string, url?: string) => boolean;
+/**
+ * @description: Whether this page is running inside an iframe. Returns false under SSR.
+ *
+ * Cross-origin embedding can make `window.parent` throw on access in some engines, so the
+ * comparison is guarded: an unreadable parent means the page is framed by a foreign origin,
+ * which still counts as embedded.
+ *
+ * @return {boolean}
+ */
+export declare const isInIframe: () => boolean;
+/**
+ * @description: Turn an object into a query string and append it to a URL
  * @return {*}
  */
 export declare function appendUrl(url: string, params?: Record<string, string>): string;
 /**
- * @description: 移除拖拽事件的阴影
+ * @description: Remove the drag event's ghost image
  * @param {DragEvent} event
  * @return {*}
  */
@@ -87,11 +129,11 @@ interface ClientRatio {
     height: number;
 }
 /**
- * 跨浏览器获取可视窗口大小
+ * Get the viewport size across browsers
  */
 export declare const getWindow: () => ClientRatio;
 /**
- * @description: 返回当前网络状态，当前吞吐量，是否切换网络
+ * @description: Current network status: type, throughput, and whether the connection changed
  */
 export declare const connection: () => number | undefined;
 /**
@@ -122,173 +164,21 @@ interface ReturnType {
     jitter: number;
 }
 /**
- * @description: 图片请求
+ * @description: Request an image (used to time the network)
  * @param {string} url
  * @return {Promise<ImageLoadError | number>}
  */
 export declare const imageRequest: (url?: string) => Promise<number>;
 /**
- * @description: 间隔一定时间，执行指定的函数
+ * @description: Run a function repeatedly at a fixed interval
  * @param {HandlerFunction} handler
  * @param {array} params
  */
 export declare const durationHandler: <T, U>(handler: (...args: T[]) => U, ...params: T[]) => ((a: number) => Promise<U>);
 /**
- * @description: 通过请求来测试当前网络的 ping 值
+ * @description: Measure the network's ping by timing requests
  * @param {*} options
  */
 export declare const networkSpeed: (options: Options) => Promise<ReturnType>;
 export declare const isSafari: () => boolean | undefined | string;
-export interface MessageHandler<T = unknown, R = unknown> {
-    (payload: T): Promise<R> | R;
-}
-export interface MessageData<T = unknown> {
-    type: string;
-    payload: T;
-    id?: string;
-    isResponse?: boolean;
-    isError?: boolean;
-    /** 通道标识：用于隔离同一窗口上的多个 bridge（默认 DEFAULT_CHANNEL） */
-    channel?: string;
-    /** 发送方实例 id：用于避免 bridge 处理自己发出的请求（自答自问） */
-    senderId?: string;
-}
-export interface PendingRequest<R = unknown> {
-    resolve: (value: R) => void;
-    reject: (error: unknown) => void;
-}
-export declare const BRIDGE_MARKER = "__ranuts_bridge__";
-export declare const DEFAULT_CHANNEL = "default";
-/**
- * Bridge 注册事件，供 client 消费
- */
-export declare class PostMessageBridge {
-    private targetWindow;
-    private targetOrigin;
-    private messageHandlers;
-    private pendingRequests;
-    private channel;
-    private senderId;
-    private available;
-    constructor(targetWindow?: Window, targetOrigin?: string, channel?: string);
-    private post;
-    receive: (event: MessageEvent) => void;
-    on: <T = unknown, R = unknown>(type: string, handler: MessageHandler<T, R>) => void;
-    off: (type: string) => void;
-    send: <T = unknown, R = unknown>(type: string, payload: T) => Promise<R>;
-    broadcast: <T = unknown>(data: {
-        type: string;
-        payload: T;
-    }) => void;
-    destroy: () => void;
-}
-export interface BridgeManagerOptions {
-    id?: string;
-    targetOrigin?: string;
-    targetWindow?: Window;
-    /** 通道标识：需要隔离同一窗口上的多个连接时显式指定，两端须一致 */
-    channel?: string;
-}
-export declare class BridgeManager {
-    private static instance;
-    private bridges;
-    private constructor();
-    static getInstance(): BridgeManager;
-    connectClient: ({ id, targetOrigin, targetWindow, channel, }: BridgeManagerOptions) => {
-        bridge: PostMessageBridge;
-        id: string;
-    };
-    getClient: (id: string) => PostMessageBridge | undefined;
-    removeClient: (id: string) => void;
-    removeAllClient: () => void;
-    broadcast: <T = unknown>(payload: {
-        type: string;
-        payload: T;
-    }) => void;
-    sendTo: <T = unknown, R = unknown>(id: string, type: string, payload: T) => Promise<R>;
-}
-export declare const bridgeManager: BridgeManager;
-export interface BroadcastPayload {
-    type: string;
-    payload: unknown;
-}
-export interface CallToPayload<T = unknown> {
-    id: string;
-    type: string;
-    payload: T;
-}
-export declare const Client: {
-    connect: ({ id, targetWindow, targetOrigin, channel, }: BridgeManagerOptions) => {
-        bridge: PostMessageBridge;
-        id: string;
-    };
-    remove: (id: string) => void;
-    removeAll: () => void;
-    /** 广播消息到所有 Platform */
-    broadcast: (payload: BroadcastPayload) => void;
-    /** 发送消息到指定 Platform */
-    call: <T = unknown, R = unknown>({ id, type, payload }: CallToPayload<T>) => Promise<R>;
-    /** 广播消息到所有所有可以接收消息的窗口 (为了安全考虑，不建议使用) */
-    broadcastToAll: (payload: BroadcastPayload) => void;
-};
-export declare const initPlatform: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => {
-    destroy: () => void;
-};
-export declare const Platform: {
-    init: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => {
-        destroy: () => void;
-    };
-};
-/**
- * 基于 MessagePort 的点对点桥接（方案 B，作为新 API 提供）。
- *
- * 与 PostMessageBridge 的「全局广播 + 过滤」不同，MessagePort 是浏览器提供的
- * 私有点对点信道：只有握手时拿到 port 的双方能通信。因此天然规避了
- * 跨窗口串消息、来源伪造、同窗口多桥串台、自答自问等问题，也无需 origin 过滤、
- * 无需协议标记、无需 base64——payload 直接走结构化克隆。
- *
- * 典型用法：
- *   // A 窗口（发起方）
- *   const bridge = openPortBridge({ targetWindow: iframe.contentWindow, targetOrigin });
- *   const res = await bridge.send('ping', { n: 1 });
- *
- *   // B 窗口（接收方）
- *   const bridge = await acceptPortBridge({ targetOrigin });
- *   bridge.on('ping', ({ n }) => n + 1);
- *
- * 也可用于已有 port 的场景（Web Worker / SharedWorker）：createPortBridge(port)。
- */
-export interface PortBridge {
-    on: <T = unknown, R = unknown>(type: string, handler: MessageHandler<T, R>) => void;
-    off: (type: string) => void;
-    send: <T = unknown, R = unknown>(type: string, payload: T) => Promise<R>;
-    broadcast: <T = unknown>(data: {
-        type: string;
-        payload: T;
-    }) => void;
-    destroy: () => void;
-}
-export interface OpenPortBridgeOptions {
-    targetWindow: Window;
-    targetOrigin?: string;
-    /** 连接名：一个页面里区分多个独立 port 连接，两端须一致（默认 'default'） */
-    name?: string;
-}
-export interface AcceptPortBridgeOptions {
-    targetOrigin?: string;
-    name?: string;
-}
-/**
- * 在任意 MessagePort 上构建 bridge（Web Worker / SharedWorker 或已握手的 port）。
- */
-export declare const createPortBridge: (port: MessagePort) => PortBridge;
-/**
- * 发起方：创建 MessageChannel，把一端交给目标窗口，自己持有另一端。
- */
-export declare const openPortBridge: ({ targetWindow, targetOrigin, name, }: OpenPortBridgeOptions) => PortBridge;
-/**
- * 接收方：等待发起方递来的 port，握手完成后返回 bridge。
- * 返回的 Promise 在收到匹配 name 的握手消息后 resolve。
- */
-export declare const acceptPortBridge: ({ targetOrigin, name, }?: AcceptPortBridgeOptions) => Promise<PortBridge>;
 export {};

package/dist/src/utils/bridge.d.ts

@@ -0,0 +1,153 @@
+export interface MessageHandler<T = unknown, R = unknown> {
+    (payload: T): Promise<R> | R;
+}
+export interface MessageData<T = unknown> {
+    type: string;
+    payload: T;
+    id?: string;
+    isResponse?: boolean;
+    isError?: boolean;
+    /** Channel id, isolating several bridges on one window (defaults to DEFAULT_CHANNEL) */
+    channel?: string;
+    /** Sender instance id, so a bridge never answers its own request */
+    senderId?: string;
+}
+export interface PendingRequest<R = unknown> {
+    resolve: (value: R) => void;
+    reject: (error: unknown) => void;
+}
+export declare const BRIDGE_MARKER = "__ranuts_bridge__";
+export declare const DEFAULT_CHANNEL = "default";
+/**
+ * Bridge registration event, consumed by the client
+ */
+export declare class PostMessageBridge {
+    private targetWindow;
+    private targetOrigin;
+    private messageHandlers;
+    private pendingRequests;
+    private channel;
+    private senderId;
+    private available;
+    constructor(targetWindow?: Window, targetOrigin?: string, channel?: string);
+    private post;
+    receive: (event: MessageEvent) => void;
+    on: <T = unknown, R = unknown>(type: string, handler: MessageHandler<T, R>) => void;
+    off: (type: string) => void;
+    send: <T = unknown, R = unknown>(type: string, payload: T) => Promise<R>;
+    broadcast: <T = unknown>(data: {
+        type: string;
+        payload: T;
+    }) => void;
+    destroy: () => void;
+}
+export interface BridgeManagerOptions {
+    id?: string;
+    targetOrigin?: string;
+    targetWindow?: Window;
+    /** Channel id; set it to isolate several connections on one window. Both ends must agree. */
+    channel?: string;
+}
+export declare class BridgeManager {
+    private static instance;
+    private bridges;
+    private constructor();
+    static getInstance(): BridgeManager;
+    connectClient: ({ id, targetOrigin, targetWindow, channel, }: BridgeManagerOptions) => {
+        bridge: PostMessageBridge;
+        id: string;
+    };
+    getClient: (id: string) => PostMessageBridge | undefined;
+    removeClient: (id: string) => void;
+    removeAllClient: () => void;
+    broadcast: <T = unknown>(payload: {
+        type: string;
+        payload: T;
+    }) => void;
+    sendTo: <T = unknown, R = unknown>(id: string, type: string, payload: T) => Promise<R>;
+}
+export declare const bridgeManager: BridgeManager;
+export interface BroadcastPayload {
+    type: string;
+    payload: unknown;
+}
+export interface CallToPayload<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+}
+export declare const Client: {
+    connect: ({ id, targetWindow, targetOrigin, channel, }: BridgeManagerOptions) => {
+        bridge: PostMessageBridge;
+        id: string;
+    };
+    remove: (id: string) => void;
+    removeAll: () => void;
+    /** Broadcast to every Platform */
+    broadcast: (payload: BroadcastPayload) => void;
+    /** Send to a named Platform */
+    call: <T = unknown, R = unknown>({ id, type, payload }: CallToPayload<T>) => Promise<R>;
+    /** Broadcast to every window that can receive it (discouraged — it is a security risk) */
+    broadcastToAll: (payload: BroadcastPayload) => void;
+};
+export declare const initPlatform: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => {
+    destroy: () => void;
+};
+export declare const Platform: {
+    init: typeof initPlatform;
+};
+/**
+ * A point-to-point bridge over MessagePort.
+ *
+ * Unlike PostMessageBridge's broadcast-then-filter model, a MessagePort is a private
+ * point-to-point channel provided by the browser: only the two parties holding the port
+ * after the handshake can talk. That rules out cross-window leakage, forged origins,
+ * cross-talk between bridges on one window and self-answering by construction — with no
+ * origin filter, no protocol marker and no base64, since the payload goes straight through
+ * structured clone.
+ *
+ * Typical use:
+ *   // Window A (initiator)
+ *   const bridge = openPortBridge({ targetWindow: iframe.contentWindow, targetOrigin });
+ *   const res = await bridge.send('ping', { n: 1 });
+ *
+ *   // Window B (acceptor)
+ *   const bridge = await acceptPortBridge({ targetOrigin });
+ *   bridge.on('ping', ({ n }) => n + 1);
+ *
+ * It also works where a port already exists (Web Worker / SharedWorker): createPortBridge(port).
+ */
+export interface PortBridge {
+    on: <T = unknown, R = unknown>(type: string, handler: MessageHandler<T, R>) => void;
+    off: (type: string) => void;
+    send: <T = unknown, R = unknown>(type: string, payload: T) => Promise<R>;
+    broadcast: <T = unknown>(data: {
+        type: string;
+        payload: T;
+    }) => void;
+    destroy: () => void;
+}
+export interface OpenPortBridgeOptions {
+    targetWindow: Window;
+    targetOrigin?: string;
+    /** Connection name, telling independent port connections apart on one page. Both ends must agree (defaults to 'default'). */
+    name?: string;
+}
+export interface AcceptPortBridgeOptions {
+    targetOrigin?: string;
+    name?: string;
+}
+/**
+ * Build a bridge on any MessagePort (a Web Worker, a SharedWorker, or a port from a completed handshake).
+ */
+export declare const createPortBridge: (port: MessagePort) => PortBridge;
+/**
+ * Initiator: create a MessageChannel, hand one port to the target window and keep the other.
+ */
+export declare const openPortBridge: ({ targetWindow, targetOrigin, name, }: OpenPortBridgeOptions) => PortBridge;
+/**
+ * Acceptor: wait for the port the initiator hands over and return the bridge once the
+ * handshake completes. The returned promise resolves on a handshake message with a matching
+ * name.
+ */
+export declare const acceptPortBridge: ({ targetOrigin, name, }?: AcceptPortBridgeOptions) => Promise<PortBridge>;

package/dist/src/utils/canvas.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @description: Degrees to radians
+ * @param {number} deg angle in degrees
+ * @return {number} angle in radians
+ */
+export declare const getAngle: (deg: number) => number;
+/**
+ * @description: The point on a circle at a given angle
+ * @param {number} deg angle in radians
+ * @param {number} r radius
+ * @return {[number, number]} the coordinates [x, y]
+ */
+export declare const getArcPointerByDeg: (deg: number, r: number) => [number, number];
+/**
+ * @description: The tangent line at a point on a circle
+ * @param {number} x x coordinate
+ * @param {number} y y coordinate
+ * @return {Array<number>} [slope, intercept]
+ */
+export declare const getTangentByPointer: (x: number, y: number) => Array<number>;
+/**
+ * @description: Trace a pie slice with arc(), including the gutter between slices.
+ * Builds the path only — no fill or stroke, so the caller decides how to paint it.
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {number} maxRadius outer radius
+ * @param {number} start start angle in radians
+ * @param {number} end end angle in radians
+ * @param {number} gutter width of the gap between slices
+ */
+export declare const fanShapedByArc: (ctx: CanvasRenderingContext2D, maxRadius: number, start: number, end: number, gutter: number) => void;
+/**
+ * @description: Trace a rounded rectangle with arc(). A corner radius larger than half the
+ * shorter side is clamped to half, so adjacent corners cannot overlap. Builds the path only
+ * — no fill or stroke.
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {number[]} rest [x, y, w, h, r]
+ */
+export declare const roundRectByArc: (ctx: CanvasRenderingContext2D, ...[x, y, w, h, r]: number[]) => void;
+/**
+ * @description: Translate a CSS `linear-gradient(...)` string into a Canvas CanvasGradient.
+ *
+ * createLinearGradient only takes a start and an end point, while CSS describes direction
+ * as an angle — so the circle is split into eight 45° sectors and the tangent turns the
+ * angle back into start/end coordinates on the rectangle's boundary.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {number} x x of the rectangle's top-left corner
+ * @param {number} y y of the rectangle's top-left corner
+ * @param {number} w rectangle width
+ * @param {number} h rectangle height
+ * @param {string} background a string such as `linear-gradient(90deg, red, blue)`
+ * @return {CanvasGradient} assignable straight to fillStyle / strokeStyle
+ */
+export declare const getLinearGradient: (ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, background: string) => CanvasGradient;

package/dist/src/utils/chain.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @description: Chainable DOM operations
+ * (tag) (key value) (children)
+ * @return {HTMLElement}
+ */
+export declare class Chain {
+    listener: Map<string, Map<string, EventListener>>;
+    element: HTMLElement;
+    constructor(tagName: string, options?: ElementCreationOptions);
+    /**
+     * @description: Create an element
+     * @param {string} tagName
+     * @param {ElementCreationOptions} options
+     * @return {Chain}
+     */
+    create: (tagName: string, options?: ElementCreationOptions) => HTMLElement;
+    /**
+     * @description: Set an attribute on the current element
+     * @param {string} name
+     * @param {string} value
+     * @return {Chain}
+     */
+    setAttribute: (name: string, value: string) => Chain;
+    /**
+     * @description: Remove an attribute from the current element
+     * @param {string} name
+     * @return {Chain}
+     */
+    removeAttribute: (name: string) => Chain;
+    /**
+     * @description: Append a child to the current element
+     * @param {HTMLElement} child
+     * @return {ChainElement}
+     */
+    append: (child: HTMLElement) => Chain;
+    /**
+     * @description: Remove a child from the current element
+     * @param {HTMLElement} child
+     * @return {Chain}
+     */
+    remove: (child: HTMLElement) => Chain;
+    /**
+     * @description: Set the current element's text content
+     * @param {string} text
+     * @return {Chain}
+     */
+    setTextContent: (text: string) => Chain;
+    /**
+     * @description: Set styles on the current element
+     * @param {string} name
+     * @param {string} value
+     * @return {Chain}
+     */
+    setStyle: (name: string, value: string) => Chain;
+    private addElementByType;
+    /**
+     * @description: Append children to the current element
+     * @return {Chain}
+     */
+    addChild: (child: Chain | Chain[] | HTMLElement | HTMLElement[]) => Chain;
+    /**
+     * @description: Add an event listener to the current element
+     * @param {string} type
+     * @param {EventListener} listener
+     * @return {Chain}
+     */
+    listen: <K extends keyof HTMLElementEventMap>(type: K, listener: EventListener, options?: boolean | AddEventListenerOptions) => Chain;
+    /**
+     * @description: Remove an event listener from the current element
+     * @param {string} type
+     * @return {Chain}
+     */
+    clearListener: <K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions) => Chain;
+    /**
+     * @description: Remove every event listener from the current element
+     * @return {Chain}
+     */
+    clearAllListener: () => Chain;
+}
+export declare const create: (tagName: string, options?: ElementCreationOptions) => Chain;