@puresnake/snake-ui 0.0.0-stage → 0.0.1

package/libs/hooks/useToast.ts

@@ -0,0 +1,116 @@
+import {
+    SNAKE_TOAST_EVENT_HIDE,
+    SNAKE_TOAST_EVENT_SHOW,
+    SNAKE_TOAST_GLOBAL_EVENT_HIDE,
+    SNAKE_TOAST_GLOBAL_EVENT_SHOW,
+    getEventWithCurrentPage,
+    type ToastPayload
+} from '../config/toast';
+import { emitter } from '../function/emitter';
+
+export type UseToastShowOptions = ToastPayload;
+
+export type UseToast = {
+    /**
+     * 显示 toast
+     * - show('文本')
+     * - show({ title, type, duration, ... })
+     */
+    show: (titleOrOptions: string | UseToastShowOptions) => void;
+    /** 关闭 toast */
+    close: () => void;
+    /** 成功 */
+    success: (titleOrOptions: string | UseToastShowOptions) => void;
+    /** 错误 */
+    error: (titleOrOptions: string | UseToastShowOptions) => void;
+    /** 警告 */
+    warning: (titleOrOptions: string | UseToastShowOptions) => void;
+    /** 信息 */
+    info: (titleOrOptions: string | UseToastShowOptions) => void;
+    /** 加载中（默认常驻，需 close 关闭） */
+    loading: (titleOrOptions: string | UseToastShowOptions) => void;
+};
+
+export type UseToastOptions = {
+    /** 是否使用全局根部 <snake-toast global />，默认 true；为 false 时走页面级 <snake-toast /> */
+    global?: boolean;
+    /** 是否使用页面级 <snake-toast page /> 或某个页面的 <snake-toast page="pageId" /> */
+    page?: boolean | string;
+};
+
+function normalize(titleOrOptions: string | UseToastShowOptions): UseToastShowOptions {
+    if (typeof titleOrOptions === 'string') return { title: titleOrOptions };
+    return titleOrOptions || {};
+}
+
+function getPage(optionsOrGlobal: UseToastOptions | boolean): string {
+    if (typeof optionsOrGlobal === 'boolean') {
+        return '';
+    }
+    if (optionsOrGlobal.page && typeof optionsOrGlobal.page === 'string' && optionsOrGlobal.page !== '') {
+        return optionsOrGlobal.page;
+    }
+    return '';
+}
+
+/**
+ * Toast 函数式调用
+ * @description 需要页面/应用中至少存在一个 <snake-toast global /> 或 <snake-toast page /> 实例用于承接事件；不影响原 ref 调用方式。
+ *
+ * 支持两种调用方式：
+ * - 应用级 useToast() / useToast(true) / useToast({ global: true })
+ * - 页面级 useToast(false) / useToast({ page: true }) / useToast({ page: 'pageId' })（pageId 应和页面中 <snake-toast page="pageId" /> 的 page 属性一致）
+ */
+export function useToast(optionsOrGlobal: UseToastOptions | boolean = true): UseToast {
+    const isGlobal = typeof optionsOrGlobal === 'boolean' ? optionsOrGlobal === true : !!optionsOrGlobal.global;
+    const isPage = typeof optionsOrGlobal === 'boolean' ? optionsOrGlobal === false : !!optionsOrGlobal.page;
+    const showEvent = isGlobal
+        ? SNAKE_TOAST_GLOBAL_EVENT_SHOW
+        : isPage
+          ? getEventWithCurrentPage(SNAKE_TOAST_EVENT_SHOW, getPage(optionsOrGlobal))
+          : '';
+    const hideEvent = isGlobal
+        ? SNAKE_TOAST_GLOBAL_EVENT_HIDE
+        : isPage
+          ? getEventWithCurrentPage(SNAKE_TOAST_EVENT_HIDE, getPage(optionsOrGlobal))
+          : '';
+
+    function emitShow(payload: UseToastShowOptions) {
+        if (showEvent) {
+            emitter.emit(showEvent, payload);
+        }
+    }
+
+    function emitHide() {
+        if (hideEvent) {
+            emitter.emit(hideEvent, undefined);
+        }
+    }
+
+    function show(titleOrOptions: string | UseToastShowOptions) {
+        emitShow(normalize(titleOrOptions));
+    }
+
+    function close() {
+        emitHide();
+    }
+
+    function withType(type: string, titleOrOptions: string | UseToastShowOptions) {
+        const options = normalize(titleOrOptions);
+        emitShow({ ...options, type });
+    }
+
+    return {
+        show,
+        close,
+        success: (v: string | UseToastShowOptions) => withType('success', v),
+        error: (v: string | UseToastShowOptions) => withType('error', v),
+        warning: (v: string | UseToastShowOptions) => withType('warning', v),
+        info: (v: string | UseToastShowOptions) => withType('info', v),
+        loading: (v: string | UseToastShowOptions) => {
+            const options = normalize(v);
+            // loading 通常需要常驻，除非用户显式传 duration
+            emitShow({ ...options, loading: true, duration: options.duration ?? 0 });
+        }
+    };
+}

package/libs/index.ts

@@ -0,0 +1,18 @@
+export {
+    RuntimeError,
+    configureRuntime,
+    getRuntimeConfig,
+    getRuntimeOptions,
+    requireCache,
+    requireRequest,
+    resetRuntime,
+    runtimeOptionsKey
+} from './runtime';
+export type { CacheAdapter, RequestAdapter, RuntimeConfig, RuntimeOptions } from './runtime';
+export * from './foundation';
+export * from './config';
+export * from './function';
+export * from './hooks';
+export * from './request';
+export * from './cms';
+export * from './form';

package/libs/request/auto-http.ts

@@ -0,0 +1 @@
+export { AutoHttp, isFunction, isPromise } from './index';

package/libs/request/index.ts

@@ -0,0 +1,343 @@
+import type { RequestAdapter } from '../runtime';
+import type { App } from 'vue';
+import { deepMerge } from '../function';
+import { translate } from '../../locale';
+import type {
+    RequestConfig,
+    RequestInterceptor,
+    RequestMeta,
+    RequestMethod,
+    RequestOptions,
+    RequestResponse,
+    RequestSetup,
+    RequestTransport
+} from '../config/types';
+
+const defaultConfig: Required<Omit<RequestConfig, 'baseUrl'>> & Pick<RequestConfig, 'baseUrl'> = {
+    baseUrl: '',
+    header: {},
+    timeout: 60000,
+    dataType: 'json',
+    responseType: 'text',
+    method: 'POST',
+    meta: { loading: false, toast: false, originalData: true }
+};
+
+export class RequestError extends Error {
+    readonly kind: 'canceled' | 'http' | 'transport' | 'interceptor';
+    readonly config?: RequestOptions;
+    readonly response?: unknown;
+    readonly statusCode?: number;
+    /** 原始宿主网络错误，例如支付宝小程序返回的 errMsg。 */
+    readonly platformError?: unknown;
+
+    constructor(
+        message: string,
+        options: {
+            kind?: RequestError['kind'];
+            config?: RequestOptions;
+            response?: unknown;
+            statusCode?: number;
+            platformError?: unknown;
+            cause?: unknown;
+        } = {}
+    ) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'RequestError';
+        this.kind = options.kind || 'transport';
+        this.config = options.config;
+        this.response = options.response;
+        this.statusCode = options.statusCode;
+        this.platformError = options.platformError;
+    }
+}
+
+function joinUrl(baseUrl: string, url: string): string {
+    if (!baseUrl || /^https?:\/\//i.test(url)) return url;
+    return `${baseUrl.replace(/\/$/, '')}/${url.replace(/^\//, '')}`;
+}
+
+function isHttpResponse(value: unknown): value is RequestResponse {
+    return Boolean(value && typeof value === 'object' && typeof (value as RequestResponse).statusCode === 'number');
+}
+
+function isSuccessfulStatus(statusCode: number): boolean {
+    return statusCode >= 200 && statusCode < 300;
+}
+
+function getErrorMessage(error: unknown, fallback: string): string {
+    if (typeof error === 'string' && error) return error;
+    if (error && typeof error === 'object') {
+        const message =
+            (error as { errMsg?: unknown; message?: unknown }).errMsg || (error as { message?: unknown }).message;
+        if (typeof message === 'string' && message) return message;
+    }
+    return fallback;
+}
+
+let loadingCount = 0;
+
+function showLoading(): void {
+    loadingCount += 1;
+    if (loadingCount > 1) return;
+    if (typeof uni !== 'undefined' && typeof uni.showLoading === 'function') {
+        uni.showLoading({ title: translate('common.loading'), mask: true });
+    }
+}
+
+function hideLoading(): void {
+    loadingCount = Math.max(0, loadingCount - 1);
+    if (loadingCount === 0 && typeof uni !== 'undefined' && typeof uni.hideLoading === 'function') uni.hideLoading();
+}
+
+function showError(message: string): void {
+    if (typeof uni !== 'undefined' && typeof uni.showToast === 'function') {
+        uni.showToast({ title: message, icon: 'none' });
+    }
+}
+
+function uniTransport(options: RequestOptions): Promise<RequestResponse> {
+    return new Promise((resolve, reject) => {
+        if (typeof uni === 'undefined' || typeof uni.request !== 'function') {
+            reject(new RequestError('[Snake UI] uni.request is unavailable.', { kind: 'transport', config: options }));
+            return;
+        }
+        // meta、baseUrl 和 params 是 Snake 的内部配置，不应透传给各小程序运行时。
+        const { baseUrl: _baseUrl, meta: _meta, params: _params, ...platformOptions } = options;
+        uni.request({
+            ...platformOptions,
+            method: options.method || 'GET',
+            data: options.data ?? options.params,
+            // 支付宝小程序会把 HTTP 401 等非成功状态送入 fail，但 complete 仍能提供 statusCode。
+            // 只要收到 HTTP 状态就交给上层响应拦截器；没有状态码时才是网络层失败。
+            complete: result => {
+                if (isHttpResponse(result)) {
+                    resolve(result);
+                    return;
+                }
+                reject(
+                    new RequestError(getErrorMessage(result, translate('network.error')), {
+                        kind: 'transport',
+                        config: options,
+                        platformError: result,
+                        cause: result
+                    })
+                );
+            }
+        });
+    });
+}
+
+export class Request {
+    config: RequestConfig = deepMerge(defaultConfig, {});
+    interceptor: RequestInterceptor = {};
+    private transport?: RequestTransport;
+    private legacyAdapter?: RequestAdapter;
+
+    setConfig(config: RequestConfig = {}): void {
+        this.config = deepMerge(this.config, config);
+    }
+
+    setInterceptor(interceptor: RequestInterceptor = {}): void {
+        this.interceptor = { ...this.interceptor, ...interceptor };
+    }
+
+    setTransport(transport?: RequestTransport): void {
+        this.transport = transport;
+    }
+
+    setLegacyAdapter(adapter?: RequestAdapter): void {
+        this.legacyAdapter = adapter;
+    }
+
+    private mergeOptions(options: RequestOptions): RequestOptions {
+        const meta = deepMerge((this.config.meta || {}) as RequestMeta, options.meta || {});
+        const header = deepMerge((this.config.header || {}) as Record<string, unknown>, options.header || {});
+        return {
+            ...this.config,
+            ...options,
+            url: joinUrl(this.config.baseUrl || '', options.url),
+            method: options.method || 'POST',
+            header,
+            meta
+        };
+    }
+
+    private async send(options: RequestOptions): Promise<RequestResponse | unknown> {
+        // 自定义 transport 优先；legacy adapter 仅兼容 GET/POST，其余方法仍交由 uni.request。
+        if (this.transport) return this.transport(options);
+        if (this.legacyAdapter && options.method === 'GET') {
+            return {
+                data: await this.legacyAdapter.get(options.url, options.params || (options.data as any)),
+                statusCode: 200
+            };
+        }
+        if (this.legacyAdapter && options.method === 'POST') {
+            return {
+                data: await this.legacyAdapter.post(options.url, (options.data || {}) as Record<string, unknown>),
+                statusCode: 200
+            };
+        }
+        return uniTransport(options);
+    }
+
+    async request<T = unknown>(options: RequestOptions): Promise<T> {
+        let config = this.mergeOptions(options);
+        if (this.interceptor.request) {
+            let intercepted: RequestOptions | false;
+            try {
+                intercepted = await this.interceptor.request(config);
+            } catch (error) {
+                throw new RequestError('[Snake UI] request interceptor failed.', {
+                    kind: 'interceptor',
+                    config,
+                    cause: error
+                });
+            }
+            if (intercepted === false) {
+                throw new RequestError(translate('network.canceled'), { kind: 'canceled', config });
+            }
+            config = intercepted;
+        }
+        const meta = config.meta || {};
+        if (meta.loading) showLoading();
+        try {
+            const raw = await this.send(config);
+            if (isHttpResponse(raw)) raw.config = config;
+            // originalData=true 时 interceptor 接收完整平台响应，状态码校验也由它负责；否则本层校验并仅传 data。
+            if (isHttpResponse(raw) && !meta.originalData && !isSuccessfulStatus(raw.statusCode)) {
+                throw new RequestError(`HTTP ${raw.statusCode}`, {
+                    kind: 'http',
+                    config,
+                    response: raw,
+                    statusCode: raw.statusCode
+                });
+            }
+            const response = meta.originalData || !isHttpResponse(raw) ? raw : raw.data;
+            if (!this.interceptor.response) return response as T;
+            let intercepted: T | false;
+            try {
+                intercepted = await this.interceptor.response(response, config);
+            } catch (error) {
+                throw new RequestError('[Snake UI] response interceptor failed.', {
+                    kind: 'interceptor',
+                    config,
+                    response,
+                    cause: error
+                });
+            }
+            if (intercepted === false) {
+                throw new RequestError('[Snake UI] response rejected by interceptor.', {
+                    kind: 'interceptor',
+                    config,
+                    response
+                });
+            }
+            return intercepted as T;
+        } catch (error) {
+            const normalized =
+                error instanceof RequestError
+                    ? error
+                    : new RequestError(getErrorMessage(error, translate('network.error')), {
+                          kind: 'transport',
+                          config,
+                          platformError: error,
+                          cause: error
+                      });
+            if (meta.toast) showError(normalized.message);
+            throw normalized;
+        } finally {
+            if (meta.loading) hideLoading();
+        }
+    }
+
+    get<T = unknown>(url: string, data: Record<string, unknown> = {}, options: Partial<RequestOptions> = {}) {
+        return this.request<T>({ ...options, url, data, params: data, method: 'GET' });
+    }
+
+    post<T = unknown>(url: string, data: unknown = {}, options: Partial<RequestOptions> = {}) {
+        return this.request<T>({ ...options, url, data, method: 'POST' });
+    }
+
+    put<T = unknown>(url: string, data: unknown = {}, options: Partial<RequestOptions> = {}) {
+        return this.request<T>({ ...options, url, data, method: 'PUT' });
+    }
+
+    delete<T = unknown>(url: string, data: unknown = {}, options: Partial<RequestOptions> = {}) {
+        return this.request<T>({ ...options, url, data, method: 'DELETE' });
+    }
+
+    reset(): void {
+        this.config = deepMerge(defaultConfig, {});
+        this.interceptor = {};
+        this.transport = undefined;
+        this.legacyAdapter = undefined;
+        loadingCount = 0;
+    }
+}
+
+/** 共享请求单例。 */
+export const http = new Request();
+
+export interface HttpPluginOptions {
+    requestConfig?: RequestConfig;
+    interceptor?: RequestInterceptor;
+}
+
+/**
+ * Installs the shared request singleton as `$http`.
+ */
+export const httpPlugin = {
+    install(app: App, options: HttpPluginOptions = {}): void {
+        if (options.interceptor) http.setInterceptor(options.interceptor);
+        if (options.requestConfig) http.setConfig(options.requestConfig);
+        (app.config.globalProperties as Record<string, unknown>).$http = http;
+    }
+};
+
+export function configureHttp(setup?: RequestSetup, adapter?: RequestAdapter): Request {
+    if (setup?.config) http.setConfig(setup.config);
+    if (setup?.interceptor) http.setInterceptor(setup.interceptor);
+    if (setup && 'transport' in setup) http.setTransport(setup.transport);
+    if (adapter) http.setLegacyAdapter(adapter);
+    return http;
+}
+
+export function isFunction(value: unknown): value is (...args: any[]) => unknown {
+    return typeof value === 'function';
+}
+
+export function isPromise(value: unknown): value is Promise<unknown> {
+    return Boolean(
+        value &&
+        typeof (value as Promise<unknown>).then === 'function' &&
+        typeof (value as Promise<unknown>).catch === 'function'
+    );
+}
+
+export class AutoHttp {
+    static Builder = class<T = unknown> {
+        constructor(private readonly instance: Request | ((options: RequestOptions) => Promise<T>)) {}
+
+        dispatch(urlConfig: Record<string, RequestOptions>, extra: Record<string, unknown> = {}): Record<string, any> {
+            const api: Record<string, any> = {};
+            for (const name of Object.keys(urlConfig)) api[name] = this.use.bind(this, urlConfig[name]);
+            return { ...api, ...extra };
+        }
+
+        use(
+            urlConfig: RequestOptions,
+            config: Partial<Omit<RequestOptions, 'url'>> & { url?: string | (() => string) } = {}
+        ): Promise<T> {
+            const url: string = isFunction(config.url)
+                ? `${urlConfig.url}${config.url()}`
+                : (config.url ?? urlConfig.url);
+            const { url: _url, ...overrides } = config;
+            const method = (config.method ?? urlConfig.method ?? 'GET') as RequestMethod;
+            const options = deepMerge(urlConfig, { ...overrides, url, method }) as RequestOptions;
+            return this.instance instanceof Request ? this.instance.request<T>(options) : this.instance(options);
+        }
+    };
+}
+
+export default httpPlugin;

package/libs/runtime/accessors.ts

@@ -0,0 +1,55 @@
+import { getRuntimeOptions } from './context';
+import { RuntimeError, type CacheAdapter, type RequestAdapter, type RuntimeConfig } from './types';
+
+/**
+ * 面向组件的运行时访问器。
+ * 所有缺失能力都在这里附带组件名报错，调用方无需各自判断或复制错误文案。
+ */
+export function requireRequest(component: string): RequestAdapter {
+    const request = getRuntimeOptions().request;
+    if (!request) throw new RuntimeError(component, 'request');
+    return request;
+}
+
+export function requireCache(component: string): CacheAdapter {
+    const cache = getRuntimeOptions().cache;
+    if (!cache) throw new RuntimeError(component, 'cache');
+    return cache;
+}
+
+export function getRuntimeConfig(component: string): Readonly<RuntimeConfig> {
+    const config = getRuntimeOptions().config;
+    if (!config) throw new RuntimeError(component, 'config');
+    return config;
+}
+
+/** 为组件创建带组件名的请求访问门面，统一保留缺失能力报错上下文。 */
+export function createRequestClient(component: string) {
+    return {
+        get<T = unknown>(url: string, params?: Record<string, unknown>): Promise<T> {
+            return requireRequest(component).get<T>(url, params);
+        },
+        post<T = unknown>(url: string, data?: Record<string, unknown>): Promise<T> {
+            return requireRequest(component).post<T>(url, data);
+        }
+    };
+}
+
+/** 为组件创建带组件名的缓存访问门面，统一保留缺失能力报错上下文。 */
+export function createCacheClient(component: string) {
+    return {
+        get<T = unknown>(key: string): T | undefined {
+            return requireCache(component).get<T>(key);
+        },
+        set<T = unknown>(key: string, value: T, ttlSeconds?: number): void {
+            requireCache(component).set(key, value, ttlSeconds);
+        },
+        delete(key: string): void {
+            requireCache(component).delete(key);
+        }
+    };
+}
+
+export function getConfig(component: string): Readonly<RuntimeConfig> {
+    return getRuntimeConfig(component);
+}

package/libs/runtime/context.ts

@@ -0,0 +1,40 @@
+import type { InjectionKey } from 'vue';
+import type { RuntimeOptions } from './types';
+
+/**
+ * 运行时上下文只保存宿主应用注入的可选能力。
+ * 它是模块级状态，供非 Vue 组件场景读取；Vue 组件同时可通过 runtimeOptionsKey 注入。
+ */
+const runtime: RuntimeOptions = {};
+
+/** 提供给 Vue 组件树的只读运行时上下文 key。 */
+export const runtimeOptionsKey: InjectionKey<Readonly<RuntimeOptions>> = Symbol('snake-ui-options');
+
+/**
+ * 合并宿主注入的能力。运行时上下文不负责主题、语言等 UI 初始化，
+ * 那些职责由 foundation 单独处理。
+ */
+export function configureRuntime(options: RuntimeOptions = {}): Readonly<RuntimeOptions> {
+    if (options.request !== undefined) runtime.request = options.request;
+    if (options.cache !== undefined) runtime.cache = options.cache;
+    if (options.config !== undefined) {
+        runtime.config = {
+            ...runtime.config,
+            ...options.config
+        };
+    }
+    if (options.cms !== undefined) runtime.cms = options.cms;
+    return runtime;
+}
+
+export function getRuntimeOptions(): Readonly<RuntimeOptions> {
+    return runtime;
+}
+
+/** 仅用于测试或重新初始化场景，清除全部宿主注入能力。 */
+export function resetRuntime(): void {
+    delete runtime.request;
+    delete runtime.cache;
+    delete runtime.config;
+    delete runtime.cms;
+}

package/libs/runtime/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 宿主运行时能力的唯一入口。
+ *
+ * 这里仅管理组件库需要由业务应用提供的 request、cache、config、cms。
+ * 主题、语言、HTTP 初始化和 `$snake` 全局 API 由 foundation 与根入口负责，
+ * 避免把“运行时依赖注入”和“UI 初始化”混在同一个模块。
+ */
+export { configureRuntime, getRuntimeOptions, resetRuntime, runtimeOptionsKey } from './context';
+export {
+    createCacheClient,
+    createRequestClient,
+    getConfig,
+    getRuntimeConfig,
+    requireCache,
+    requireRequest
+} from './accessors';
+export { RuntimeError } from './types';
+export type { CacheAdapter, RequestAdapter, RuntimeConfig, RuntimeOptions } from './types';

package/libs/runtime/types.ts

@@ -0,0 +1,49 @@
+import type { DebugLevel, LocaleOption, RequestSetup, ThemeOption } from '../config/types';
+import type { CmsOptions } from '../cms/types';
+
+/** 由宿主项目实现的最小请求能力；Snake UI 不绑定某个 HTTP 库。 */
+export interface RequestAdapter {
+    get<T = unknown>(url: string, params?: Record<string, unknown>): Promise<T>;
+    post<T = unknown>(url: string, data?: Record<string, unknown>): Promise<T>;
+}
+
+export interface CacheAdapter {
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): void;
+    delete(key: string): void;
+}
+
+export interface RuntimeConfig {
+    baseUrl?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * 宿主应用在安装 Snake UI 时提供的运行期能力。
+ * request、cache、config 与 cms 会存入 runtime；其余字段由 UI 初始化阶段消费。
+ */
+export interface RuntimeOptions {
+    request?: RequestAdapter;
+    cache?: CacheAdapter;
+    config?: RuntimeConfig;
+    theme?: ThemeOption;
+    locale?: LocaleOption;
+    http?: RequestSetup;
+    debugMode?: boolean | DebugLevel | DebugLevel[];
+    cms?: CmsOptions;
+}
+
+export class RuntimeError extends Error {
+    readonly component: string;
+    readonly capability: keyof RuntimeOptions;
+
+    constructor(component: string, capability: keyof RuntimeOptions) {
+        super(
+            `[Snake UI] ${component} requires the "${capability}" adapter. ` +
+                `Configure it with app.use(SnakeUI, { ${capability}: ... }).`
+        );
+        this.name = 'RuntimeError';
+        this.component = component;
+        this.capability = capability;
+    }
+}