ranui 0.1.10-alpha.9 → 0.2.0-alpha.0

package/dist/utils/builder/mocks.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A minimal mock of DocumentFragment for SSR environments.
+ */
+export declare class DocumentFragmentMock {
+    childrenList: (HTMLElementMock | string)[];
+    appendChild(node: any): any;
+    serialize(): string;
+    querySelector(selector: string): HTMLElementMock | null;
+    querySelectorAll(selector: string): HTMLElementMock[];
+}
+/**
+ * A robust mock of HTMLElement for SSR environments.
+ */
+export declare class HTMLElementMock {
+    tagName: string;
+    attributes: Map<string, string>;
+    inlineStyles: Map<string, string>;
+    childrenList: (HTMLElementMock | string | DocumentFragmentMock)[];
+    shadowRoot: ShadowRootMock | null;
+    textContent: string | null;
+    content?: DocumentFragmentMock;
+    private eventListeners;
+    style: {
+        setProperty: (k: string, v: string) => void;
+        removeProperty: (k: string) => boolean;
+    };
+    classList: {
+        add: (...names: string[]) => void;
+        remove: (...names: string[]) => void;
+        toggle: (name: string) => void;
+        contains: (name: string) => boolean;
+    };
+    private _innerHTML;
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    constructor(tag?: string);
+    get hidden(): boolean;
+    set hidden(val: boolean);
+    setAttribute(k: string, v: string): void;
+    getAttribute(k: string): string | null;
+    removeAttribute(k: string): void;
+    hasAttribute(k: string): boolean;
+    appendChild(node: any): any;
+    attachShadow(options: ShadowRootInit): ShadowRoot;
+    querySelector(selector: string): HTMLElementMock | null;
+    querySelectorAll(selector: string): HTMLElementMock[];
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+    dispatchEvent(event: Event): boolean;
+    serialize(tagNameOverride?: string): string;
+}
+export declare class ShadowRootMock {
+    host: HTMLElementMock;
+    options: ShadowRootInit;
+    childrenList: (HTMLElementMock | string | DocumentFragmentMock)[];
+    adoptedStyleSheets: string[];
+    constructor(host: HTMLElementMock, options: ShadowRootInit);
+    appendChild(node: any): any;
+    querySelector(selector: string): HTMLElementMock | null;
+    querySelectorAll(selector: string): HTMLElementMock[];
+    serialize(): string;
+}

package/dist/utils/builder/selectors.d.ts

@@ -0,0 +1,4 @@
+import type { DocumentFragmentMock, HTMLElementMock } from './mocks';
+export type MockNode = HTMLElementMock | DocumentFragmentMock | string;
+export declare const matchSelector: (node: HTMLElementMock, selector: string) => boolean;
+export declare const collectMatches: (nodes: MockNode[], selector: string, result: HTMLElementMock[]) => void;

package/dist/utils/builder/signal.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Reactive primitives — signal / createEffect / computed / batch
+ *
+ * Design reference: SwiftUI @Observable + Solid.js fine-grained reactivity
+ *
+ * SwiftUI's core model:  View = f(State)
+ *   @State / @Observable — reactive source (≈ signal)
+ *   body                 — pure function of state, auto-tracks reads (≈ createEffect)
+ *   computed property    — derived, cached (≈ computed)
+ *
+ * Two improvements over a naive signal implementation, both borrowed from Solid.js:
+ *
+ *   1. Stale subscription cleanup
+ *      Before each re-run, an effect removes itself from every signal it previously
+ *      subscribed to, then re-subscribes only to signals read in this run.
+ *      Without this, conditional reads leave permanent ghost subscriptions that
+ *      trigger effects for signals they no longer care about.
+ *
+ *   2. Batching
+ *      batch(fn) defers all effect executions until fn returns, then flushes once.
+ *      Mirrors SwiftUI's automatic coalescing of mutations in the same event handler.
+ *      Without this, setting two signals triggers each dependent effect twice.
+ */
+export type Getter<T> = () => T;
+export type Setter<T> = (value: T | ((prev: T) => T)) => void;
+export interface SignalOptions<T> {
+    /** Custom equality check. Defaults to Object.is. Return true to skip update. */
+    equals?: (prev: T, next: T) => boolean;
+}
+/**
+ * Create a reactive value. Returns a [getter, setter] tuple.
+ *
+ *   const [count, setCount] = signal(0);
+ *   count()              // read — auto-tracks inside createEffect / computed
+ *   setCount(1)          // write — notifies dependents; skips if value unchanged
+ *   setCount(n => n + 1) // updater function form
+ */
+export declare function signal<T>(initial: T, options?: SignalOptions<T>): [Getter<T>, Setter<T>];
+/**
+ * Run fn immediately and re-run it whenever any signal read inside it changes.
+ * Returns a dispose function that stops the effect and cleans up subscriptions.
+ *
+ * Before each re-run, the effect removes itself from every signal it previously
+ * subscribed to (stale-subscription cleanup), then re-subscribes only to signals
+ * read in the new run.
+ *
+ * fn may return a cleanup function — called before each re-run and on dispose.
+ *
+ *   const dispose = createEffect(() => {
+ *     document.title = `Count: ${count()}`;
+ *     return () => { document.title = ''; }; // optional cleanup
+ *   });
+ *
+ *   dispose(); // stop tracking, remove from all signals
+ */
+export declare function createEffect(fn: () => void | (() => void)): () => void;
+/**
+ * Derived read-only signal. Recomputes when its dependencies change.
+ *
+ *   const [firstName, setFirstName] = signal('Jane');
+ *   const [lastName,  setLastName]  = signal('Doe');
+ *   const fullName = computed(() => `${firstName()} ${lastName()}`);
+ *
+ *   fullName() // 'Jane Doe'
+ *   setFirstName('John');
+ *   fullName() // 'John Doe'
+ */
+export declare function computed<T>(fn: () => T): Getter<T>;
+/**
+ * Run multiple signal writes as a single atomic update.
+ * All effects are deferred until fn returns, then flushed once (deduplicated).
+ *
+ * Mirrors SwiftUI's automatic coalescing of mutations within the same event handler.
+ *
+ *   // Without batch: each setter triggers effects independently (2 runs)
+ *   setFirstName('John');
+ *   setLastName('Smith');
+ *
+ *   // With batch: one flush after both writes (1 run)
+ *   batch(() => {
+ *     setFirstName('John');
+ *     setLastName('Smith');
+ *   });
+ *
+ * Nested batch() calls are safe — inner calls are absorbed by the outer batch.
+ */
+export declare function batch(fn: () => void): void;

package/dist/utils/color.d.ts

@@ -0,0 +1,52 @@
+export declare const hsv2hsl: (h: number, s: number, v: number) => {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare const hex2alpha: (aa: string) => number;
+export declare const hex2hsl: (hex: string) => {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare const hex2hsv: (hex: string) => {
+    h: number;
+    s: number;
+    v: number;
+};
+export declare const hex2rgb: (hex: string) => {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const rgb2hsv: (r: number, g: number, b: number) => {
+    h: number;
+    s: number;
+    v: number;
+};
+export declare const hsl2hsv: (h: number, s: number, l: number) => {
+    h: number;
+    s: number;
+    v: number;
+};
+export declare const hsl2rgb: (h: number, s: number, l: number) => {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const hsv2rgb: (h: number, s: number, v: number) => {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const rgb2hex: (r: number, g: number, b: number) => string;
+export declare const rgba: (r: number, g: number, b: number, a: number) => string;
+export declare const rgba2hex: (r: number, g: number, b: number, a: number) => string;
+export declare const rgba2rgb: (r: number, g: number, b: number, a: number) => {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const HEX_COLOR_REGEX: RegExp;
+export declare const RGB_REGEX: RegExp;
+export declare const RGBA_REGEX: RegExp;

package/dist/utils/component.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Honour the user's "reduce motion" OS setting in every component. Adopted into
+ * each shadow root (last, so it overrides the component's own transitions), and
+ * scoped to the shadow tree by `*`. Only active when the user has the preference set.
+ */
+export declare const REDUCED_MOTION_CSS: string;
+export declare const ensureShadowRoot: (host: HTMLElement, cssText?: string, options?: ShadowRootInit) => ShadowRoot;
+export declare const ensureShadowElement: <T extends HTMLElement>(root: ShadowRoot, selector: string, factory: () => T) => T;
+export declare const getStringAttribute: (element: HTMLElement, name: string, fallback?: string) => string;
+export declare const setStringAttribute: (element: HTMLElement, name: string, value: string | null | undefined, options?: {
+    removeEmpty?: boolean;
+}) => void;
+export declare const setBooleanAttribute: (element: HTMLElement, name: string, value: boolean, options?: {
+    aria?: string;
+}) => void;
+export declare const syncSheetAttribute: (host: HTMLElement, root: ShadowRoot, name: string, oldValue: string | null, newValue: string | null) => void;

package/dist/utils/dom.d.ts

@@ -0,0 +1,39 @@
+export declare const falseList: (string | boolean | null | undefined)[];
+/**
+ * @description: 判断这个元素上是否有 disabled 属性
+ * @param {Element} element
+ * @return {*}
+ */
+export declare const isDisabled: (element: Element) => boolean;
+/**
+ * @description: 查询指定元素的子级元素，删除他们的某一个指定 class
+ * @param {Element} parent
+ * @param {string} deleteClass
+ */
+export declare const removeClassToElementChild: (parent: Element, deleteClass: string) => void;
+/**
+ * @description: 创建 icon 的文档示例
+ */
+export declare const createIconList: () => void;
+/**
+ * @description: 动态加载脚本
+ */
+export declare const loadScript: ({ type, content }: {
+    type: string;
+    content: string;
+}) => Promise<{
+    success: boolean;
+}>;
+/**
+ * 转义 HTML 特殊字符，防止 XSS
+ */
+export declare const escapeHtml: (unsafe: any) => string;
+/**
+ * 极简的声明式模板实现
+ * 将模板字符串解析为 DocumentFragment，并对动态部分进行转义防止 XSS
+ */
+export declare const html: (strings: TemplateStringsArray, ...values: any[]) => DocumentFragment;
+/**
+ * 根据文件扩展名获取 MIME 类型
+ */
+export declare function getMimeTypeFromExtension(fileName: string): string;

package/dist/utils/error.d.ts

@@ -0,0 +1,6 @@
+export interface CustomErrorType {
+    new (m?: string): {
+        message: string;
+    };
+}
+export declare function createCustomError(msg?: string): CustomErrorType;

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

@@ -0,0 +1,53 @@
+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 `navigator.language` 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.
+     */
+    t(key: string, params?: TranslateParams): string;
+    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;

package/dist/utils/i18n.js

@@ -0,0 +1,88 @@
+var l = "ran-locale", n = (e) => {
+  if (typeof localStorage > "u") return null;
+  try {
+    return localStorage.getItem(e);
+  } catch {
+    return null;
+  }
+}, i = (e, t) => {
+  if (!(typeof localStorage > "u"))
+    try {
+      localStorage.setItem(e, t);
+    } catch {
+    }
+}, o = (e) => {
+  if (typeof navigator > "u" || !navigator.language) return null;
+  const t = navigator.language.toLowerCase();
+  return e.find((s) => s.toLowerCase() === t) ?? e.find((s) => t.startsWith(s.toLowerCase())) ?? e.find((s) => t.startsWith(`${s.toLowerCase()}-`)) ?? null;
+}, _ = class {
+  _locale;
+  _fallback;
+  _messages;
+  _persist;
+  _storageKey;
+  _handlers = /* @__PURE__ */ new Set();
+  constructor(e = {}) {
+    this._messages = { ...e.messages }, this._fallback = e.fallbackLocale ?? "en", this._persist = e.persist ?? !1, this._storageKey = e.storageKey ?? l, this._locale = this._resolveInitialLocale(e);
+  }
+  _resolveInitialLocale(e) {
+    const t = Object.keys(this._messages), s = this._persist ? n(this._storageKey) : null;
+    if (s && (this._messages[s] || t.length === 0)) return s;
+    if (e.locale) return e.locale;
+    if (e.detectNavigator) {
+      const r = o(t);
+      if (r) return r;
+    }
+    return this._fallback;
+  }
+  get locale() {
+    return this._locale;
+  }
+  getLocale() {
+    return this._locale;
+  }
+  setLocale(e) {
+    e !== this._locale && (this._locale = e, this._persist && i(this._storageKey, e), this._notify());
+  }
+  addMessages(e, t) {
+    this._messages[e] = {
+      ...this._messages[e],
+      ...t
+    };
+  }
+  getMessages(e = this._locale) {
+    return this._messages[e] ?? {};
+  }
+  get availableLocales() {
+    return Object.keys(this._messages);
+  }
+  t(e, t) {
+    const s = this._messages[this._locale]?.[e] ?? this._messages[this._fallback]?.[e] ?? e;
+    return this._interpolate(s, t);
+  }
+  _interpolate(e, t) {
+    return t ? e.replace(/\{(\w+)\}/g, (s, r) => t[r] != null ? String(t[r]) : s) : e;
+  }
+  onChange(e) {
+    return this._handlers.add(e), () => {
+      this._handlers.delete(e);
+    };
+  }
+  _notify() {
+    for (const e of this._handlers) e(this._locale);
+  }
+  destroy() {
+    this._handlers.clear();
+  }
+}, a = null;
+function h(e = {}) {
+  return a = new _(e), a;
+}
+function c() {
+  return a;
+}
+export {
+  _ as I18nCore,
+  h as createI18n,
+  c as useI18n
+};

package/dist/utils/image.d.ts

@@ -0,0 +1,39 @@
+type ImgType = HTMLImageElement | HTMLCanvasElement;
+/**
+ * 根据路径获取图片对象
+ * @param { string } src 图片路径
+ * @returns { Promise<HTMLImageElement> } 图片标签
+ */
+export declare const getImage: (src: string) => Promise<ImgType>;
+/**
+ * 切割圆角
+ * @param img 将要裁剪的图片对象
+ * @param radius 裁剪的圆角半径
+ * @returns 返回一个离屏 canvas 用于渲染
+ */
+export declare const cutRound: (img: ImgType, radius: number) => ImgType;
+/**
+ * 透明度
+ * @param img 将要处理的图片对象
+ * @param opacity 透明度
+ * @returns 返回一个离屏 canvas 用于渲染
+ */
+export declare const opacity: (img: ImgType, opacity: number) => ImgType;
+/**
+ * 权重矩阵
+ * @param radius 模糊半径
+ * @param sigma
+ * @returns 返回一个权重和为1的矩阵
+ */
+export declare const getMatrix: (radius: number, sigma?: number) => number[];
+/**
+ * 高斯模糊
+ * @param img 将要处理的图片对象
+ * @param radius 模糊半径
+ * @returns 返回一个离屏 canvas 用于渲染
+ */
+export declare const blur: (img: ImgType) => ImgType;
+export declare const getBase64Image: (imageFile: File) => Promise<{
+    base64: string | ArrayBuffer | null;
+}>;
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+export * from './builder';
+export { falseList, isDisabled, removeClassToElementChild, createIconList, loadScript, html, getMimeTypeFromExtension, } from './dom';
+export * from './error';
+export { signal, createEffect, computed, batch } from './builder/signal';
+export * from './ssr';
+export * from './video';
+export * from './component';
+export * from './theme';

package/dist/utils/math.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 转换为运算角度
+ * @param { number } deg 数学角度
+ * @return { number } 运算角度
+ */
+export declare const getAngle: (deg: number) => number;
+/**
+ * 根据角度计算圆上的点
+ * @param { number } deg 运算角度
+ * @param { number } r 半径
+ * @return { Array<number> } 坐标 [x, y]
+ */
+export declare const getArcPointerByDeg: (deg: number, r: number) => [number, number];
+/**
+ * 根据点计算切线方程
+ * @param { number } x 横坐标
+ * @param { number } y 纵坐标
+ * @return { Array<number> } [斜率，常数]
+ */
+export declare const getTangentByPointer: (x: number, y: number) => Array<number>;
+export declare const fanShapedByArc: (ctx: CanvasRenderingContext2D, maxRadius: number, start: number, end: number, gutter: number) => void;
+export declare const roundRectByArc: (ctx: CanvasRenderingContext2D, ...[x, y, w, h, r]: number[]) => void;
+/**
+ * 创建线性渐变色
+ */
+export declare const getLinearGradient: (ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, background: string) => void;

package/dist/utils/router/index.d.ts

@@ -0,0 +1,128 @@
+export interface RouteConfig {
+    path: string;
+    exact?: boolean;
+    meta?: Record<string, unknown>;
+    children?: RouteConfig[];
+}
+export type ViewTransitionMode = 'spa' | 'mpa' | 'both';
+export interface RouterConfig {
+    mode?: 'history' | 'hash';
+    base?: string;
+    routes?: RouteConfig[];
+    /**
+     * Enable View Transitions API.
+     *
+     * - `'spa'` / `true`  — wraps same-document DOM updates in document.startViewTransition().
+     * - `'mpa'`           — injects `@view-transition { navigation: auto }` for cross-document
+     *                       transitions; hooks pageswap/pagereveal for customization.
+     * - `'both'`          — spa + mpa combined; best for apps that do both client-side and
+     *                       full-page navigation.
+     *
+     * Gracefully degrades when the API is not supported.
+     */
+    viewTransition?: boolean | ViewTransitionMode;
+}
+export interface RouteLocation {
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    fullPath: string;
+}
+export type NavigationGuard = (to: RouteLocation, from: RouteLocation | null, next: (redirect?: string | false) => void) => void;
+export type RouteChangeHandler = (to: RouteLocation, from: RouteLocation | null) => void;
+export interface PageSwapEvent extends Event {
+    readonly viewTransition: ViewTransitionHandle | null;
+    readonly activation: NavigationActivation | null;
+}
+export interface PageRevealEvent extends Event {
+    readonly viewTransition: ViewTransitionHandle | null;
+}
+interface NavigationActivation {
+    readonly entry: unknown;
+    readonly from: unknown;
+    readonly navigationType: string;
+}
+interface ViewTransitionHandle {
+    readonly ready: Promise<void>;
+    readonly finished: Promise<void>;
+    readonly updateCallbackDone: Promise<void>;
+    skipTransition(): void;
+    types?: Set<string>;
+}
+export interface RouterComponentElement extends HTMLElement {
+    _syncRoutes(): void;
+}
+export declare function getSSGPath(): string | null;
+export declare function setSSGPath(path: string): void;
+export declare function clearSSGPath(): void;
+export declare class RouterCore {
+    private readonly _mode;
+    private readonly _base;
+    private readonly _routes;
+    private readonly _vtMode;
+    private readonly _beforeGuards;
+    private readonly _afterGuards;
+    private readonly _changeHandlers;
+    private readonly _pageSwapHandlers;
+    private readonly _pageRevealHandlers;
+    private readonly _components;
+    private _current;
+    private _mpaActive;
+    constructor(config?: RouterConfig);
+    get mode(): 'history' | 'hash';
+    get base(): string;
+    get routes(): RouteConfig[];
+    get currentRoute(): RouteLocation | null;
+    private _matchConfigPath;
+    /** Return the first RouteConfig whose path matches the given URL path, or null. */
+    matchRoute(path: string): RouteConfig | null;
+    /** Return all route paths declared in the router config — used to enumerate SSG pages. */
+    getStaticPaths(): string[];
+    private _enableMpa;
+    private _disableMpa;
+    private _onPageSwap;
+    private _onPageReveal;
+    _bind(component: RouterComponentElement): void;
+    _unbind(component: RouterComponentElement): void;
+    _buildLocation(path: string): RouteLocation;
+    _getCurrentPath(): string;
+    _notify(): void;
+    private _navigate;
+    push(path: string): Promise<void>;
+    replace(path: string): Promise<void>;
+    back(): void;
+    forward(): void;
+    go(delta: number): void;
+    /** Tear down MPA listeners and injected CSS. Call when the router is no longer needed. */
+    destroy(): void;
+    /** Register a navigation guard. Returns an unsubscribe function. */
+    beforeEach(guard: NavigationGuard): () => void;
+    /** Register a post-navigation hook. Returns an unsubscribe function. */
+    afterEach(handler: RouteChangeHandler): () => void;
+    /** Subscribe to route changes. Returns an unsubscribe function. */
+    onRouteChange(handler: RouteChangeHandler): () => void;
+    /**
+     * Subscribe to the cross-document `pageswap` event (fires on the outgoing page).
+     * Only active when viewTransition is 'mpa' or 'both'.
+     * Returns an unsubscribe function.
+     */
+    onPageSwap(handler: (e: PageSwapEvent) => void): () => void;
+    /**
+     * Subscribe to the cross-document `pagereveal` event (fires on the incoming page).
+     * Only active when viewTransition is 'mpa' or 'both'.
+     * Returns an unsubscribe function.
+     */
+    onPageReveal(handler: (e: PageRevealEvent) => void): () => void;
+}
+/** Create and register a global RouterCore instance. */
+export declare function createRouter(config?: RouterConfig): RouterCore;
+/** Return the current global RouterCore instance, or null if none was created. */
+export declare function useRouter(): RouterCore | null;
+/**
+ * Standalone helper — enable cross-document View Transitions without a router.
+ * Injects `@view-transition { navigation: auto }` once and returns a cleanup function.
+ *
+ * Useful for pure MPA sites that don't need a JS router at all.
+ */
+export declare function enableMpaViewTransitions(): () => void;
+export {};