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

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

@@ -45,7 +45,16 @@ export declare class Color {
     updateFromHsl(): void;
 }
 export declare const randomColor: () => Color;
-export declare const hexToRgb: (hex: string) => RegExpExecArray | null | Array<number>;
+/**
+ * @description: `#rrggbb` / `#rgb` (with or without the `#`) to `[r, g, b]`; null when it cannot be parsed.
+ *
+ * The three-digit shorthand is expanded per the CSS rule (`#abc` → `#aabbcc`), not
+ * zero-padded — padding would turn `#fff` into `#0f0f0f`, a dark grey rather than white.
+ *
+ * @param {string} hex
+ * @return {Array<number> | null}
+ */
+export declare const hexToRgb: (hex: string) => Array<number> | null;
 export declare const componentToHex: (c: string | number) => string;
 export declare const rgbToHex: (r: string | number | Array<string | number>, g?: string | number, b?: string | number) => string;
 export declare const rgbToHsl: (r: number | number[], g?: number, b?: number) => Array<number>;
@@ -53,9 +62,72 @@ export declare const hue2rgb: (p: number, q: number, t: number) => number;
 export declare const hslToRgb: (h: number | string | number[], s: number | string, l: number | string) => Array<number>;
 export declare const rgbToHsb: (r: number, g: number, b: number) => number[];
 export declare const hsbToRgb: (h: number, s: number, v: number) => number[];
-export declare const hsvToRgb: (h: number, s: number, v: number) => number[];
-export declare const hsbToHsl: (h: any, s: any, b: any) => number[];
-export declare const hsvToHsl: (h: any, s: any, b: any) => number[];
+export declare const hsvToRgb: typeof hsbToRgb;
+export declare const hsbToHsl: (h: number, s: number, b: number) => number[];
+export declare const hsvToHsl: typeof hsbToHsl;
+/** Alias of `rgbToHsb` — HSV and HSB are two names for the same colour space. */
+export declare const rgbToHsv: typeof rgbToHsb;
+/**
+ * @description: `#rrggbb` / `#rgb` to `[h, s, b]`; null when the hex is invalid.
+ * @param {string} hex
+ * @return {number[] | null}
+ */
+export declare const hexToHsb: (hex: string) => number[] | null;
+export declare const hexToHsv: typeof hexToHsb;
+/**
+ * @description: `[h, s, l]` to `[h, s, b]`
+ * @param {number} h hue, 0–360
+ * @param {number} s saturation, 0–100
+ * @param {number} l lightness, 0–100
+ * @return {number[]}
+ */
+export declare const hslToHsb: (h: number, s: number, l: number) => number[];
+export declare const hslToHsv: typeof hslToHsb;
+/**
+ * @description: A two-digit hex alpha channel (`ff` / `80` / `00`) to a 0–100 percentage.
+ * @param {string} aa two hex digits
+ * @return {number} 0 ~ 100
+ */
+export declare const hexToAlpha: (aa: string) => number;
+/**
+ * @description: Build a CSS `rgba()` string. Alpha is 0–100 rather than 0–1, matching the
+ * percentage convention the rest of this module uses.
+ * @param {number} r 0~255
+ * @param {number} g 0~255
+ * @param {number} b 0~255
+ * @param {number} a 0~100
+ * @return {string}
+ */
+export declare const rgbaString: (r: number, g: number, b: number, a: number) => string;
+/**
+ * @description: Composite a translucent colour **over white**, giving the equivalent opaque rgb.
+ *
+ * For places that do not accept alpha (writing back a 6-digit hex, say). Note the backdrop
+ * is hard-coded to white: under a dark theme the result comes out too light, so composite
+ * against your own backdrop when you need a different one.
+ *
+ * @param {number} r 0~255
+ * @param {number} g 0~255
+ * @param {number} b 0~255
+ * @param {number} a 0~100
+ * @return {number[]} [r, g, b]
+ */
+export declare const rgbaToRgb: (r: number, g: number, b: number, a: number) => number[];
+/**
+ * @description: Composite a translucent colour over white and return it as a 6-digit hex.
+ * @param {number} r 0~255
+ * @param {number} g 0~255
+ * @param {number} b 0~255
+ * @param {number} a 0~100
+ * @return {string}
+ */
+export declare const rgbaToHex: (r: number, g: number, b: number, a: number) => string;
+/** `#rgb` / `#rrggbb` (the `#` is required) */
+export declare const HEX_COLOR_REGEX: RegExp;
+/** `rgb(r,g,b)`, no spaces — strip whitespace before matching */
+export declare const RGB_REGEX: RegExp;
+/** `rgba(r,g,b,a)`, no spaces — strip whitespace before matching */
+export declare const RGBA_REGEX: RegExp;
 export declare class ColorScheme {
     palette: Color[];
     constructor(colorVal: (string | number)[], angleArray: number[]);

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

@@ -2,7 +2,7 @@ export type Next = () => Promise<never> | Promise<void>;
 type Middleware<T> = (context: T, next: Next) => any;
 type ComposedMiddleware<T> = (context: T, next?: Next) => Promise<void>;
 /**
- * @description: 将异步函数转化为同步的方式进行执行
+ * @description: Run a chain of async functions as if it were sequential
  * @param {Array} middleware
  * @return {*}
  */

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

@@ -1 +1,19 @@
-export declare const handleConsole: (hooks?: (...args: unknown[]) => void) => void;
+export type ConsoleMethod = 'log' | 'info' | 'warn' | 'error' | 'assert';
+/**
+ * @description: Tap into `console` so every call also reaches your hook, while still printing
+ * as usual. Used to ship console output to a monitoring backend.
+ *
+ * Returns a **restore function** — patching a global without one is a one-way door: tests
+ * cannot clean up after themselves, and a hot reload re-patches an already-patched console
+ * until every log is nested through a dozen wrappers.
+ *
+ * @param {Function} hooks receives `(type, ...args)` for every console call
+ * @return {Function} restore — puts the original console methods back
+ * @example
+ * ```ts
+ * const restore = handleConsole((type, ...args) => send({ type, args }));
+ * // on teardown
+ * restore();
+ * ```
+ */
+export declare const handleConsole: (hooks?: (...args: unknown[]) => void) => (() => void);

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

@@ -1,7 +1,29 @@
+export interface Debounced<T extends (...args: any[]) => any> {
+    (this: unknown, ...args: Parameters<T>): void;
+    /** Cancel the pending invocation, if any. */
+    cancel: () => void;
+    /** Invoke the pending call immediately (e.g. force a flush before form submit). */
+    flush: () => void;
+    /** Whether an invocation is currently waiting to fire. */
+    pending: () => boolean;
+}
 /**
- * @description: 防抖
- * @param {any} fn
- * @param {*} ms
- * @return {*}
+ * @description: Debounce — on a burst of calls, run only the last one, **`ms` milliseconds
+ * after the calls stop**. For input suggestions, window resize, autosave — anything that
+ * only cares about the final state.
+ *
+ * Preserves the caller's `this` and the arguments of the last call. The returned function
+ * carries `cancel` / `flush`: call `cancel()` on unmount, otherwise the pending timer fires
+ * into an already destroyed context.
+ *
+ * @param {Function} fn function to debounce
+ * @param {number} ms quiet period in milliseconds, defaults to 500
+ * @return {Debounced} wrapped function with cancel / flush / pending
+ * @example
+ * ```ts
+ * const save = debounce((draft: string) => api.save(draft), 800);
+ * input.addEventListener('input', (e) => save(e.target.value));
+ * onUnmount(() => save.cancel());
+ * ```
  */
-export declare const debounce: (fn: any, ms?: number) => any;
+export declare const debounce: <T extends (...args: any[]) => any>(fn: T, ms?: number) => Debounced<T>;

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

@@ -1,5 +1,5 @@
 /**
- * @description: 判断当前设备
+ * @description: Detect the current device
  * @param {*} function
  * @return {*}
  */
@@ -12,14 +12,42 @@ export declare enum DEVICE {
 export type CurrentDevice = 'ipad' | 'android' | 'iphone' | 'pc';
 export declare const currentDevice: () => CurrentDevice;
 export declare const isClient: boolean;
+/** Viewport breakpoint, matching where the mobile layout takes over */
+export declare const MOBILE_MEDIA_QUERY = "(max-width: 768px)";
 /**
- * @description: 判断是否是微信浏览器的函数
+ * @description: Read whether a media query currently matches, synchronously. Returns false under SSR.
+ *
+ * Prefer this over `isMobile()` when asking "is this mobile": UA sniffing identifies the
+ * **device**, a media query the **viewport** — and only the latter is right when a desktop
+ * window is narrowed or a tablet is rotated.
+ * @param {string} query the media query
+ * @return {boolean}
+ */
+export declare const matchMediaQuery: (query: string) => boolean;
+/**
+ * @description: Watch a media query. The callback **fires once synchronously with the
+ * current value** (so the caller need not read the initial state separately), then on every
+ * change. Returns an unsubscribe function — call it when the component is destroyed or the
+ * page is disposed; an unreleased MediaQueryList listener leaks the closure and every DOM
+ * node it captured.
+ * @param {string} query the media query
+ * @param {Function} callback called when the match state changes
+ * @return {Function} unsubscribe
+ * @example
+ * ```ts
+ * const off = watchMediaQuery(MOBILE_MEDIA_QUERY, (isMobile) => render(isMobile));
+ * onCleanup(off);
+ * ```
+ */
+export declare const watchMediaQuery: (query: string, callback: (matches: boolean) => void) => (() => void);
+/**
+ * @description: Whether this is the WeChat in-app browser
  * @param {*} boolean
  * @return {*}
  */
 export declare const isWeiXin: () => boolean;
 /**
- * 是否是移动端
+ * Whether this is a mobile device
  */
 export declare const isMobile: () => boolean;
 export declare const isBangDevice: () => boolean;

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

@@ -1,105 +1,26 @@
 /**
- * @description: 给指定的元素添加指定的 class
+ * @description: Add a class to an element
  * @param {Element} element
  * @param {string} addClass
  */
 export declare const addClassToElement: (element: Element, addClass: string) => void;
 /**
- * @description: 给指定的元素移除指定的 class
+ * @description: Remove a class from an element
  * @param {Element} element
  * @param {string} removeClass
  */
 export declare const removeClassToElement: (element: Element, removeClass: string) => void;
 /**
- * @description: 创建一个 Fragment
+ * @description: Create a DocumentFragment
  * @param {Element} list
  * @return {*}
  */
 export declare const createDocumentFragment: (list: Element[]) => DocumentFragment | undefined;
 export declare function escapeHtml(string?: string | number | null): string;
 /**
- * @description: 根据 UI 稿宽度设置 rem
+ * @description: Set the root font size from the design mock's width
  * @param {*} void
  * @return {*}
  */
 export declare const setFontSize2html: (designWidth?: number) => void;
-/**
- * @description: 链式调用的 dom 操作
- * (tag) (key value) (children)
- * @return {HTMLElement}
- */
-export declare class Chain {
-    listener: Map<string, Map<string, EventListener>>;
-    element: HTMLElement;
-    constructor(tagName: string, options?: ElementCreationOptions);
-    /**
-     * @description: 创建元素
-     * @param {string} tagName
-     * @param {ElementCreationOptions} options
-     * @return {Chain}
-     */
-    create: (tagName: string, options?: ElementCreationOptions) => HTMLElement;
-    /**
-     * @description: 设置当前元素的属性
-     * @param {string} name
-     * @param {string} value
-     * @return {Chain}
-     */
-    setAttribute: (name: string, value: string) => Chain;
-    /**
-     * @description: 移除当前元素的属性
-     * @param {string} name
-     * @return {Chain}
-     */
-    removeAttribute: (name: string) => Chain;
-    /**
-     * @description: 当前元素添加子元素
-     * @param {HTMLElement} child
-     * @return {ChainElement}
-     */
-    append: (child: HTMLElement) => Chain;
-    /**
-     * @description: 当前元素移除子元素
-     * @param {HTMLElement} child
-     * @return {Chain}
-     */
-    remove: (child: HTMLElement) => Chain;
-    /**
-     * @description: 给当前元素设置文本内容
-     * @param {string} text
-     * @return {Chain}
-     */
-    setTextContent: (text: string) => Chain;
-    /**
-     * @description: 给当前元素设置样式
-     * @param {string} name
-     * @param {string} value
-     * @return {Chain}
-     */
-    setStyle: (name: string, value: string) => Chain;
-    private addElementByType;
-    /**
-     * @description: 给当前元素添加子元素
-     * @return {Chain}
-     */
-    addChild: (child: Chain | Chain[] | HTMLElement | HTMLElement[]) => Chain;
-    /**
-     * @description: 给当前元素添加事件监听
-     * @param {string} type
-     * @param {EventListener} listener
-     * @return {Chain}
-     */
-    listen: <K extends keyof HTMLElementEventMap>(type: K, listener: EventListener, options?: boolean | AddEventListenerOptions) => Chain;
-    /**
-     * @description: 移除当前元素的事件监听
-     * @param {string} type
-     * @return {Chain}
-     */
-    clearListener: <K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions) => Chain;
-    /**
-     * @description: 移除当前元素的所有事件监听
-     * @return {Chain}
-     */
-    clearAllListener: () => Chain;
-}
-export declare const create: (tagName: string, options?: ElementCreationOptions) => Chain;
+export { Chain, create } from './chain';

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

@@ -1 +1,18 @@
-export declare const handleError: (hooks?: (error: Error | PromiseRejectionEvent | ErrorEvent) => void) => void;
+export type ErrorPayload = Error | PromiseRejectionEvent | ErrorEvent;
+/**
+ * @description: Listen for uncaught errors and unhandled promise rejections, in the capture
+ * phase so a handler further down cannot swallow them first.
+ *
+ * Returns an **unsubscribe function**. Without one these listeners live for the lifetime of
+ * the page: a hot reload adds a second pair, then a third, and every error is reported N times.
+ *
+ * @param {Function} hooks receives the error / rejection event
+ * @return {Function} unsubscribe
+ * @example
+ * ```ts
+ * const off = handleError((error) => report({ payload: { error: String(error) } }));
+ * // on teardown
+ * off();
+ * ```
+ */
+export declare const handleError: (hooks?: (error: ErrorPayload) => void) => (() => void);

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

@@ -0,0 +1,61 @@
+/**
+ * @description: EventManager — a scoped listener registry built on AbortController.
+ *
+ * The problem it solves is removing every listener you installed. A manual
+ * `removeEventListener` needs the **exact** same function reference and options used to
+ * register — wrap the handler in an arrow function anywhere along the way and it can never
+ * be removed, so a component that mounts and unmounts repeatedly leaks listeners.
+ * AbortController reduces all of that to a single `abort()`.
+ *
+ * In a Web Component:
+ *
+ *   private _events = new EventManager();
+ *
+ *   connectedCallback() {
+ *     this._events
+ *       .on(this._input, 'input', this.handleInput)
+ *       .on(this, 'click', this.handleClick, { capture: true });
+ *   }
+ *
+ *   disconnectedCallback() {
+ *     this._events.abort(); // remove every listener and reset for the next connect
+ *   }
+ *
+ * In an ordinary page:
+ *
+ *   function initSection(container: HTMLElement) {
+ *     const scope = new EventManager();
+ *
+ *     scope
+ *       .on(input, 'input', handleSearch)
+ *       .delegate(container, '[data-action]', 'click', (ev, target) => {
+ *         handleAction(target.getAttribute('data-action'));
+ *       });
+ *
+ *     return () => scope.abort(); // call when the section is torn down
+ *   }
+ */
+export declare class EventManager {
+    private ac;
+    constructor();
+    /** The underlying AbortSignal — pass it straight to addEventListener's options when needed. */
+    get signal(): AbortSignal;
+    on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, handler: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: Omit<AddEventListenerOptions, 'signal'>): this;
+    on(target: EventTarget, type: string, handler: EventListener, options?: Omit<AddEventListenerOptions, 'signal'>): this;
+    /**
+     * @description: Event delegation — one listener on `parent`, invoking `handler` only when
+     * the event came from a descendant matching `selector`.
+     *
+     * The handler receives the original event and the matched element.
+     *
+     *   scope.delegate(list, '.item', 'click', (ev, item) => {
+     *     console.log(item.getAttribute('data-id'));
+     *   });
+     */
+    delegate<K extends keyof HTMLElementEventMap>(parent: HTMLElement, selector: string, type: K, handler: (ev: HTMLElementEventMap[K], target: Element) => void, options?: Omit<AddEventListenerOptions, 'signal'>): this;
+    /**
+     * @description: Remove every registered listener and reset the internal AbortController.
+     * Safe to call repeatedly; later on() / delegate() calls start from a clean scope.
+     */
+    abort(): void;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Promise wrappers around FileReader. The native FileReader exposes three callbacks —
+ * `onload` / `onerror` / `onabort` — and forgetting `onabort` leaves the promise pending
+ * forever when the user cancels; all three exits are wired up here.
+ */
+/**
+ * @description: Read a File / Blob as an ArrayBuffer
+ * @param {Blob} blob
+ * @return {Promise<ArrayBuffer>}
+ */
+export declare const readFileAsArrayBuffer: (blob: Blob) => Promise<ArrayBuffer>;
+/**
+ * @description: Read a File / Blob as a Uint8Array (pair with checkEncoding / arrayBufferToString for encoding sniffing)
+ * @param {Blob} blob
+ * @return {Promise<Uint8Array>}
+ */
+export declare const readFileAsUint8Array: (blob: Blob) => Promise<Uint8Array>;
+/**
+ * @description: Read a File / Blob as text
+ * @param {Blob} blob
+ * @param {string} encoding charset, defaults to utf-8; sniff with checkEncoding first when the encoding is unknown
+ * @return {Promise<string>}
+ */
+export declare const readFileAsText: (blob: Blob, encoding?: string) => Promise<string>;
+/**
+ * @description: Read a File / Blob as a data: URL (image previews and the like)
+ * @param {Blob} blob
+ * @return {Promise<string>}
+ */
+export declare const readFileAsDataURL: (blob: Blob) => Promise<string>;

package/dist/src/utils/i18n/index.js

@@ -0,0 +1 @@
+import{n as r,r as s,t as a}from"../../../i18n-Cf5TtRb4.js";export{a as I18nCore,r as createI18n,s as useI18n};

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

@@ -0,0 +1,69 @@
+export type MessageDict = Record<string, string>;
+export type LocaleMessages = Record<string, MessageDict>;
+export type TranslateParams = Record<string, string | number>;
+export type LocaleChangeHandler = (locale: string) => void;
+export interface I18nConfig {
+    /** Initial locale. Overridden by a persisted choice when `persist` is on. */
+    locale?: string;
+    /** Locale used when a key is missing in the active locale. Defaults to 'en'. */
+    fallbackLocale?: string;
+    /** Locale → key → string. */
+    messages?: LocaleMessages;
+    /** Persist the active locale to localStorage. Defaults to false. */
+    persist?: boolean;
+    /** localStorage key used when `persist` is on. Defaults to 'ran-locale'. */
+    storageKey?: string;
+    /** Seed the initial locale from the browser's language preferences when nothing else applies. */
+    detectNavigator?: boolean;
+}
+export declare class I18nCore {
+    private _locale;
+    private _fallback;
+    private _messages;
+    private _persist;
+    private _storageKey;
+    private _handlers;
+    constructor(config?: I18nConfig);
+    private _resolveInitialLocale;
+    /** The active locale. */
+    get locale(): string;
+    getLocale(): string;
+    /** Switch locale; persists (when enabled) and notifies subscribers. No-op if unchanged. */
+    setLocale(locale: string): void;
+    /** Merge a dictionary into a locale (creating it if needed). */
+    addMessages(locale: string, dict: MessageDict): void;
+    getMessages(locale?: string): MessageDict;
+    /** Locales that have a dictionary registered. */
+    get availableLocales(): string[];
+    /**
+     * Translate a key against the active locale, falling back to the fallback
+     * locale and finally the key itself. `{param}` placeholders are interpolated;
+     * `{{` / `}}` are escapes for literal `{` / `}` (see {@link I18nCore._interpolate}).
+     */
+    t(key: string, params?: TranslateParams): string;
+    /**
+     * Substitute `{param}` placeholders and unescape literal braces.
+     *
+     * Grammar (a single left-to-right pass, so escapes and placeholders never
+     * fight each other), matching the format-string convention used by Rust
+     * `format!`, Python `str.format`, and .NET `String.Format`:
+     * - `{{` → literal `{`
+     * - `}}` → literal `}`
+     * - `{name}` → `params.name` (stringified), or left untouched when the param
+     *   is absent, so a stray placeholder is visible rather than silently blank.
+     *
+     * A lone `{`/`}` or a `{ spaced }` group is not a placeholder and is emitted
+     * verbatim, so CSS/JSON/code fragments in a message pass through unharmed.
+     * To wrap a value in literal braces, double the outer pair: `{{{name}}}`.
+     */
+    private _interpolate;
+    /** Subscribe to locale changes. Returns an unsubscribe function. */
+    onChange(handler: LocaleChangeHandler): () => void;
+    private _notify;
+    /** Remove all subscribers. */
+    destroy(): void;
+}
+/** Create and register the global i18n singleton. */
+export declare function createI18n(config?: I18nConfig): I18nCore;
+/** Return the active global i18n instance, or null if none was created. */
+export declare function useI18n(): I18nCore | null;