@puresnake/snake-ui 0.0.0-stage → 0.0.2

package/libs/function/throttle.ts

@@ -0,0 +1,36 @@
+import type { CancelableFunction } from './debounce';
+
+/**
+ * 节流：wait 窗口内最多执行一次，且窗口结束时会补发最后一次尾随调用，
+ * 保证「最后一次触发不丢」。
+ * @param callback 目标回调，参数由包装函数透传
+ * @param wait 节流窗口，单位 ms，默认 300
+ * @returns 带 cancel() 的包装函数；cancel 同时重置计时基准
+ */
+export function throttle<Args extends unknown[]>(callback: (...args: Args) => void, wait = 300): CancelableFunction<Args> {
+    let lastCall = 0;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const wrapped = ((...args: Args) => {
+        const remaining = wait - (Date.now() - lastCall);
+        if (remaining <= 0) {
+            if (timer) clearTimeout(timer);
+            timer = undefined;
+            lastCall = Date.now();
+            callback(...args);
+            return;
+        }
+        if (!timer) {
+            timer = setTimeout(() => {
+                timer = undefined;
+                lastCall = Date.now();
+                callback(...args);
+            }, remaining);
+        }
+    }) as CancelableFunction<Args>;
+    wrapped.cancel = () => {
+        if (timer) clearTimeout(timer);
+        timer = undefined;
+        lastCall = 0;
+    };
+    return wrapped;
+}

package/libs/function/timeFormat.ts

@@ -0,0 +1,27 @@
+/**
+ * 时间格式化，占位符区分大小写：yyyy 年、mm 月、dd 日、hh 时、MM 分、ss 秒
+ * （分钟使用大写 MM）。非法日期返回空串。
+ * @param value 时间戳 / 日期字符串 / Date；10 位数字按秒级时间戳升位为毫秒
+ * @param pattern 格式模板，默认 'yyyy-mm-dd hh:MM:ss'
+ */
+export function formatTime(value: string | number | Date, pattern = 'yyyy-mm-dd hh:MM:ss'): string {
+    // 10 位数字/字符串按秒级时间戳处理，统一换算为毫秒
+    let timeValue: string | number | Date = value;
+    if ((typeof timeValue === 'number' || typeof timeValue === 'string') && String(timeValue).length === 10) {
+        timeValue = Number(timeValue) * 1000;
+    }
+    const date = timeValue instanceof Date ? timeValue : new Date(timeValue);
+    if (Number.isNaN(date.getTime())) return '';
+    const parts: Record<string, string> = {
+        yyyy: String(date.getFullYear()),
+        mm: String(date.getMonth() + 1).padStart(2, '0'),
+        dd: String(date.getDate()).padStart(2, '0'),
+        hh: String(date.getHours()).padStart(2, '0'),
+        MM: String(date.getMinutes()).padStart(2, '0'),
+        ss: String(date.getSeconds()).padStart(2, '0')
+    };
+    return pattern.replace(/yyyy|mm|dd|hh|MM|ss/g, token => parts[token]);
+}
+
+// timeFormat 是 formatTime 的别名。
+export { formatTime as timeFormat };

package/libs/function/timeFrom.ts

@@ -0,0 +1,27 @@
+import { formatTime } from './timeFormat';
+
+/** 归一化为 Date：数字或纯数字串在绝对值 < 1e12 时按秒级时间戳升位为毫秒。 */
+function normalizeTime(value: string | number | Date): Date {
+    if (value instanceof Date) return new Date(value.getTime());
+    if (typeof value === 'number' || /^\d+(?:\.\d+)?$/.test(String(value).trim())) {
+        const numeric = Number(value);
+        return new Date(Math.abs(numeric) < 1e12 ? numeric * 1000 : numeric);
+    }
+    return new Date(value);
+}
+
+/**
+ * 时间转为「多久之前」：刚刚 / n分钟前 / n小时前 / n天前，超过 30 天回落为 yyyy-mm-dd。
+ * @param now 当前时间基准，默认 Date.now()；注入固定值便于测试
+ */
+export function timeFrom(value: string | number | Date, now = Date.now()): string {
+    const date = normalizeTime(value);
+    const timestamp = date.getTime();
+    if (!Number.isFinite(timestamp)) return '';
+    const seconds = Math.max(0, Math.floor((now - timestamp) / 1000));
+    if (seconds < 60) return '刚刚';
+    if (seconds < 3600) return `${Math.floor(seconds / 60)}分钟前`;
+    if (seconds < 86400) return `${Math.floor(seconds / 3600)}小时前`;
+    if (seconds < 2592000) return `${Math.floor(seconds / 86400)}天前`;
+    return formatTime(date, 'yyyy-mm-dd');
+}

package/libs/function/toast.ts

@@ -0,0 +1,10 @@
+/**
+ * 无图标 toast（icon: 'none'，最多展示两行）。
+ * 默认时长 2000ms，不支持传 icon / 配置对象。
+ * @param title 提示文案；空值静默忽略
+ * @param duration 展示时长，单位 ms
+ */
+export function toast(title: string, duration = 2000): void {
+    if (!title) return;
+    uni.showToast({ title, icon: 'none', duration });
+}

package/libs/function/trim.ts

@@ -0,0 +1,11 @@
+/**
+ * 去除字符串空格。
+ * @param value 输入字符串
+ * @param position 去除位置：'both'（默认）| 'left' | 'right' | 'all'
+ */
+export function trim(value: string, position: 'both' | 'left' | 'right' | 'all' = 'both'): string {
+    if (position === 'left') return value.replace(/^\s+/, '');
+    if (position === 'right') return value.replace(/\s+$/, '');
+    if (position === 'all') return value.replace(/\s+/g, '');
+    return value.trim();
+}

package/libs/function/type2icon.ts

@@ -0,0 +1,11 @@
+/**
+ * 语义类型 → 图标名，供 toast / modal 等结果类组件取配套图标；
+ * 未识别的 type 落到 info-circle。
+ * warning 映射为 'warning'。
+ */
+export function type2icon(type: string): string {
+    return (
+        ({ success: 'checkmark-circle', warning: 'warning', error: 'close-circle', info: 'info-circle' } as Record<string, string>)[type] ||
+        'info-circle'
+    );
+}

package/libs/function/unit.ts

@@ -0,0 +1,45 @@
+export type UnitValue = number | string | null | undefined;
+
+const BARE_NUMBER_PATTERN = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * 给数值补单位：裸数字（含多值简写中的每一段）追加 unit，其余原样返回；
+ * null / undefined / 空串统一归一为 "0" + unit。
+ * 空值不透传，而是归零。
+ */
+export function addUnit(value: UnitValue = 0, unit = 'rpx'): string {
+    if (value === null || value === undefined || value === '') return `0${unit}`;
+    if (typeof value === 'number') return `${value}${unit}`;
+    const normalized = String(value).trim();
+    // 多值（空格分隔，用于 margin/padding 等简写）：逐段套用单值规则，已有单位的段保持原样。
+    if (normalized.includes(' ')) {
+        return normalized
+            .split(/\s+/)
+            .map(segment => (BARE_NUMBER_PATTERN.test(segment) ? `${segment}${unit}` : segment))
+            .join(' ');
+    }
+    return BARE_NUMBER_PATTERN.test(normalized) ? `${normalized}${unit}` : normalized;
+}
+
+// node 直载测试等无 uni 环境返回 0，由 pxToRpx 归入非法视口兜底
+function getViewportWidth(): number {
+    if (typeof uni === 'undefined') return 0;
+    return Number(uni.getSystemInfoSync().windowWidth);
+}
+
+/**
+ * px 换算 rpx（750 设计稿基准）。
+ * @param value 像素值
+ * @param viewportWidth 视口宽度，默认实时读取；注入固定值便于测试与固定稿计算
+ * @returns 形如 "375rpx" 的字符串；value 或视口宽度非法时返回 "0rpx"
+ */
+export function pxToRpx(value: UnitValue = 0, viewportWidth = getViewportWidth()): string {
+    const numericValue = Number(value);
+    const numericViewportWidth = Number(viewportWidth);
+
+    if (!Number.isFinite(numericValue) || !Number.isFinite(numericViewportWidth) || numericViewportWidth <= 0) {
+        return '0rpx';
+    }
+
+    return `${(numericValue * 750) / numericViewportWidth}rpx`;
+}

package/libs/hooks/index.ts

@@ -0,0 +1,11 @@
+export * from './useRect';
+export * from './useTheme';
+export * from './useColor';
+export * from './useLocale';
+export * from './useRouter';
+export * from './useDebounce';
+export * from './useThrottle';
+export * from './useToast';
+export * from './useModal';
+export * from './useParent';
+export * from './useChildren';

package/libs/hooks/useChildren.ts

@@ -0,0 +1,125 @@
+import {
+    provide,
+    reactive,
+    getCurrentInstance,
+    type VNode,
+    type InjectionKey,
+    type VNodeNormalizedChildren,
+    type ComponentPublicInstance,
+    type ComponentInternalInstance
+} from 'vue';
+
+/**
+ * uni-app 的小程序 Vue 运行时没有导出 `isVNode`，但 VNode 本身保持 Vue 的
+ * `__v_isVNode` 标记。使用该标记避免生成对缺失运行时导出的静态导入。
+ */
+const isVNode = (value: unknown): value is VNode =>
+    Boolean(value && typeof value === 'object' && (value as { __v_isVNode?: unknown }).__v_isVNode === true);
+
+export function flattenVNodes(children: VNode | VNodeNormalizedChildren): VNode[] {
+    const result: VNode[] = [];
+
+    const traverse = (children: VNode | VNodeNormalizedChildren) => {
+        const vNode = Array.isArray(children) ? children : [children];
+        vNode.forEach(child => {
+            if (Array.isArray(child)) {
+                traverse(child);
+            } else if (isVNode(child) && child.component?.subTree) {
+                result.push(child);
+                traverse(child.component.subTree);
+            } else if (isVNode(child) && Array.isArray(child.children)) {
+                traverse(child.children);
+            } else if (isVNode(child)) {
+                result.push(child);
+            }
+        });
+    };
+
+    traverse(children);
+
+    return result;
+}
+
+const findVNodeIndex = (vnodes: VNode[], vnode: VNode) => {
+    const index = vnodes.indexOf(vnode);
+    if (index === -1) {
+        // 异步渲染等场景下 vnode 引用可能已变化；带 key 时退回 type + key 匹配以保持模板顺序。
+        return vnodes.findIndex(item => vnode.key !== undefined && vnode.key !== null && item.type === vnode.type && item.key === vnode.key);
+    }
+    return index;
+};
+
+/**
+ * 注册顺序可能与渲染顺序不一致（v-for / slot / 异步渲染），按父组件 vnode 树重排，
+ * 保证 children 数组与模板中的子组件顺序一致。
+ */
+export function sortChildren(
+    parent: ComponentInternalInstance,
+    publicChildren: ComponentPublicInstance[],
+    internalChildren: ComponentInternalInstance[]
+) {
+    const vnodes = parent && parent.subTree && parent.subTree.children ? flattenVNodes(parent.subTree) : [];
+    internalChildren.sort((a, b) => findVNodeIndex(vnodes, a.vnode) - findVNodeIndex(vnodes, b.vnode));
+
+    const orderedPublicChildren = internalChildren.map(item => item.proxy!);
+
+    publicChildren.sort((a, b) => {
+        const getIndex = (comp: ComponentPublicInstance) => {
+            const uid = comp.$!.uid;
+            return orderedPublicChildren.findIndex(i => i.$!.uid === uid);
+        };
+
+        return getIndex(a) - getIndex(b);
+    });
+}
+
+/**
+ * 父组件侧的关系 hook：linkChildren 时 provide 出 link / unlink / children 集合与业务上下文，
+ * 子组件经 {@link useParent} 注入。children 为公开代理数组（exposed 的 ref 已解包），
+ * 并始终按模板渲染顺序排列。
+ *
+ * Child 为子项公开代理的业务视图（按 defineExpose 的形态声明纯接口即可）；
+ * 需要自定义 Child 时两个泛型必须同时显式给出，否则 ProvideValue 推断会被关闭。
+ */
+export function useChildren<Child = ComponentPublicInstance, ProvideValue = never>(key: InjectionKey<ProvideValue>) {
+    const publicChildren: Child[] = reactive([]);
+    const internalChildren: ComponentInternalInstance[] = reactive([]);
+    const parent = getCurrentInstance()!;
+
+    const linkChildren = (value: ProvideValue = {} as ProvideValue) => {
+        const link = (child: ComponentInternalInstance) => {
+            if (child.proxy) {
+                if (internalChildren.indexOf(child) === -1) {
+                    internalChildren.push(child);
+                    publicChildren.push(child.proxy as Child);
+                    sortChildren(parent, publicChildren as ComponentPublicInstance[], internalChildren);
+                }
+            }
+        };
+
+        const unlink = (child: ComponentInternalInstance) => {
+            const index = internalChildren.indexOf(child);
+            // unlink 仅应由已 link 的子组件调用；未注册实例的 index 为 -1，调用方不得传入。
+            publicChildren.splice(index, 1);
+            internalChildren.splice(index, 1);
+        };
+
+        provide(
+            key,
+            Object.assign(
+                {
+                    link,
+                    unlink,
+                    children: publicChildren,
+                    internalChildren
+                },
+                value
+            )
+        );
+    };
+
+    return {
+        children: publicChildren,
+        linkChildren
+    };
+}

package/libs/hooks/useColor.ts

@@ -0,0 +1,5 @@
+import { setThemeColor, color } from '../config/theme';
+
+export function useColor() {
+    return { color: color, setColor: setThemeColor };
+}

package/libs/hooks/useDebounce.ts

@@ -0,0 +1,5 @@
+import { debounce } from '../function';
+
+export function useDebounce<Args extends unknown[]>(callback: (...args: Args) => void, wait?: number) {
+    return debounce(callback, wait);
+}

package/libs/hooks/useLocale.ts

@@ -0,0 +1,13 @@
+import { currentLocale, initLocale, setLocale, locales, translate as translateMessage } from '../../locale';
+
+export function useLocale(namespace?: string) {
+    const translate = (key: string, replacements?: Record<string, unknown> | unknown[], locale?: string) =>
+        translateMessage(namespace ? `${namespace}.${key}` : key, replacements, locale);
+    return {
+        currentLocale: currentLocale,
+        locales: locales,
+        t: translate,
+        initLocales: initLocale,
+        setLocale: setLocale
+    };
+}

package/libs/hooks/useModal.ts

@@ -0,0 +1,131 @@
+import {
+    SNAKE_MODAL_EVENT_SHOW,
+    SNAKE_MODAL_EVENT_HIDE,
+    SNAKE_MODAL_EVENT_CLEAR_LOADING,
+    SNAKE_MODAL_GLOBAL_EVENT_SHOW,
+    SNAKE_MODAL_GLOBAL_EVENT_HIDE,
+    SNAKE_MODAL_GLOBAL_EVENT_CLEAR_LOADING,
+    getEventWithCurrentPage,
+    type ModalPayload
+} from '../config/modal';
+import { emitter } from '../function/emitter';
+
+export type UseModalShowOptions = ModalPayload;
+
+export type UseModal = {
+    /**
+     * 显示 modal
+     * - show('内容')
+     * - show({ title, content, showCancelButton, ... })
+     */
+    show: (contentOrOptions: string | UseModalShowOptions) => void;
+    /**
+     * 显示 confirm 类型的 modal（带确认和取消按钮）
+     * - confirm('内容')
+     * - confirm({ title, content, onConfirm, onCancel })
+     */
+    confirm: (contentOrOptions: string | UseModalShowOptions) => void;
+    /** 关闭 modal */
+    close: () => void;
+    /** 清除 loading 状态 */
+    clearLoading: () => void;
+};
+
+export type UseModalOptions = {
+    /** 是否使用全局根部 <snake-modal global /> */
+    global?: boolean;
+    /** 是否使用页面级 <snake-modal page /> 或某个页面的 <snake-modal page="pageId" /> */
+    page?: boolean | string;
+};
+
+function normalize(contentOrOptions: string | UseModalShowOptions): UseModalShowOptions {
+    if (typeof contentOrOptions === 'string') {
+        return { content: contentOrOptions };
+    }
+    return contentOrOptions || {};
+}
+
+function getPage(optionsOrGlobal: UseModalOptions | boolean): string {
+    if (typeof optionsOrGlobal === 'boolean') {
+        return '';
+    }
+    if (optionsOrGlobal.page && typeof optionsOrGlobal.page === 'string' && optionsOrGlobal.page !== '') {
+        return optionsOrGlobal.page;
+    }
+    return '';
+}
+
+/**
+ * Modal 函数式调用
+ * @description 需要页面/应用中至少存在一个 <snake-modal global /> 或 <snake-modal page /> 实例用于承接事件；不影响原 v-model 调用方式。
+ *
+ * 支持两种调用方式：
+ * - 应用级 useModal() / useModal(true) / useModal({ global: true })
+ * - 页面级 useModal(false) / useModal({ page: true }) / useModal({ page: 'pageId' })（pageId 应和页面中 <snake-modal page="pageId" /> 的 page 属性一致）
+ */
+export function useModal(optionsOrGlobal: UseModalOptions | boolean = true): UseModal {
+    const isGlobal = typeof optionsOrGlobal === 'boolean' ? optionsOrGlobal === true : !!optionsOrGlobal.global;
+    const isPage = typeof optionsOrGlobal === 'boolean' ? optionsOrGlobal === false : !!optionsOrGlobal.page;
+
+    const showEvent = isGlobal
+        ? SNAKE_MODAL_GLOBAL_EVENT_SHOW
+        : isPage
+          ? getEventWithCurrentPage(SNAKE_MODAL_EVENT_SHOW, getPage(optionsOrGlobal))
+          : '';
+    const hideEvent = isGlobal
+        ? SNAKE_MODAL_GLOBAL_EVENT_HIDE
+        : isPage
+          ? getEventWithCurrentPage(SNAKE_MODAL_EVENT_HIDE, getPage(optionsOrGlobal))
+          : '';
+    const clearLoadingEvent = isGlobal
+        ? SNAKE_MODAL_GLOBAL_EVENT_CLEAR_LOADING
+        : isPage
+          ? getEventWithCurrentPage(SNAKE_MODAL_EVENT_CLEAR_LOADING, getPage(optionsOrGlobal))
+          : '';
+
+    function emitShow(payload: UseModalShowOptions) {
+        if (showEvent) {
+            emitter.emit(showEvent, payload);
+        }
+    }
+
+    function emitHide() {
+        if (hideEvent) {
+            emitter.emit(hideEvent, undefined);
+        }
+    }
+
+    function emitClearLoading() {
+        if (clearLoadingEvent) {
+            emitter.emit(clearLoadingEvent, undefined);
+        }
+    }
+
+    function show(contentOrOptions: string | UseModalShowOptions) {
+        emitShow(normalize(contentOrOptions));
+    }
+
+    function confirm(contentOrOptions: string | UseModalShowOptions) {
+        const options = normalize(contentOrOptions);
+        emitShow({
+            ...options,
+            showCancelButton: options.showCancelButton ?? true,
+            showConfirmButton: options.showConfirmButton ?? true
+        });
+    }
+
+    function clearLoading() {
+        emitClearLoading();
+    }
+
+    function close() {
+        emitHide();
+    }
+
+    return {
+        show,
+        confirm,
+        close,
+        clearLoading
+    };
+}

package/libs/hooks/useParent.ts

@@ -0,0 +1,62 @@
+import {
+    ref,
+    shallowRef,
+    inject,
+    computed,
+    onUnmounted,
+    onMounted,
+    getCurrentInstance,
+    type InjectionKey,
+    type ComponentPublicInstance,
+    type ComponentInternalInstance,
+    type Ref,
+    type ShallowRef
+} from 'vue';
+
+/**
+ * useChildren 的 linkChildren 在业务上下文之外附加的注册通道，
+ * 子侧经 inject 拿到的实际形态。
+ */
+export type RelationParent<T> = T & {
+    children: ComponentPublicInstance[];
+    link(child: ComponentInternalInstance): void;
+    unlink(child: ComponentInternalInstance): void;
+    internalChildren: ComponentInternalInstance[];
+};
+
+type UseParentResult<T> = {
+    parent: ShallowRef<RelationParent<T> | null>;
+    index: Ref<number>;
+};
+
+/**
+ * 子组件侧的关系 hook：按 InjectionKey 注入父上下文，自动注册 / 注销自身，
+ * 并暴露响应式下标。配套 {@link useChildren} 使用（provide/inject 底座）。
+ * 参数须保持裸 `InjectionKey<T>` 形态，嵌套泛型会让 T 推断失效。
+ */
+export function useParent<T>(key: InjectionKey<T>): UseParentResult<T> {
+    const result: UseParentResult<T> = {
+        parent: shallowRef<RelationParent<T> | null>(null),
+        index: ref<number>(-1)
+    };
+    // #ifdef MP-TOUTIAO
+    onMounted(() => {
+        // #endif
+        // 注入值在运行时携带 link / unlink（见 useChildren.linkChildren），此处按 RelationParent 视图读取
+        result.parent.value = inject<RelationParent<T> | null>(key, null);
+
+        if (result.parent.value) {
+            const instance = getCurrentInstance()!;
+            const { link, unlink, internalChildren } = result.parent.value;
+
+            link(instance);
+            onUnmounted(() => unlink(instance));
+
+            result.index = computed(() => internalChildren.indexOf(instance));
+        }
+        // #ifdef MP-TOUTIAO
+    });
+    // #endif
+
+    return result;
+}

package/libs/hooks/useRect.ts

@@ -0,0 +1,44 @@
+import { getCurrentInstance, nextTick, ref } from 'vue';
+
+/**
+ * useRect - 获取元素的位置信息（响应式版本）。
+ * 基础层的 function/getRect.ts 因 node 直载测试约束保持无 vue 依赖，
+ * 响应式能力（rect ref + refresh）由本 hook 提供。
+ * @param selector 选择器（如 #id 或 .class）
+ * @param all 是否获取所有匹配元素
+ * @returns rect 响应式的节点信息，refresh 主动刷新方法
+ */
+export function useRect(selector: string | null = null, all = false) {
+    const rect = ref<any>(all ? [] : null);
+    const instance = getCurrentInstance();
+
+    async function getRect(realSelector: string | null = null, delay = 0): Promise<any> {
+        const targetSelector = realSelector || selector;
+        if (!targetSelector) return rect.value;
+        await nextTick();
+        return new Promise(resolve => {
+            setTimeout(() => {
+                uni.createSelectorQuery()
+                    .in(instance?.proxy)
+                    [all ? 'selectAll' : 'select'](targetSelector as string)
+                    .boundingClientRect((res: any) => {
+                        rect.value = res;
+                        resolve(res);
+                    })
+                    .exec();
+            }, delay);
+        });
+    }
+
+    function refresh(selector?: string | null, delay?: number): Promise<any> {
+        return getRect(selector, delay);
+    }
+
+    return {
+        rect,
+        getRect,
+        refresh
+    };
+}
+
+export default useRect;

package/libs/hooks/useRouter.ts

@@ -0,0 +1,5 @@
+import { navTo, route } from '../function/route';
+
+export function useRouter() {
+    return { route, navTo };
+}

package/libs/hooks/useTheme.ts

@@ -0,0 +1,31 @@
+import { computed } from 'vue';
+import {
+    currentTheme,
+    initTheme,
+    isDarkMode,
+    setDarkMode,
+    setTheme,
+    setThemeColor,
+    color,
+    cssVars,
+    darkMode,
+    themes,
+    toggleDarkMode
+} from '../config/theme';
+
+export function useTheme() {
+    return {
+        currentTheme: currentTheme,
+        themes: themes,
+        darkMode: darkMode,
+        color: color,
+        cssVars: cssVars,
+        themeStyle: computed(() => cssVars.value),
+        initTheme: initTheme,
+        setTheme: setTheme,
+        setThemeColor: setThemeColor,
+        setDarkMode: setDarkMode,
+        toggleDarkMode: toggleDarkMode,
+        isInDarkMode: isDarkMode
+    };
+}

package/libs/hooks/useThrottle.ts

@@ -0,0 +1,5 @@
+import { throttle } from '../function';
+
+export function useThrottle<Args extends unknown[]>(callback: (...args: Args) => void, wait?: number) {
+    return throttle(callback, wait);
+}