mp-taro-kit 0.0.3 → 0.0.4

package/dist/ui/navigation/style/index.css

@@ -0,0 +1,42 @@
+.mptk-drawer__mask,
+.mptk-dropdown__mask {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  background-color: var(--mptk-fg);
+  opacity: 0.4;
+}
+
+.mptk-drawer__panel {
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  background-color: var(--mptk-surface-1);
+  padding-top: var(--mptk-space-4);
+  padding-right: var(--mptk-space-4);
+  padding-bottom: var(--mptk-space-4);
+  padding-left: var(--mptk-space-4);
+}
+
+.mptk-drawer__panel--left {
+  left: 0;
+}
+
+.mptk-drawer__panel--right {
+  right: 0;
+}
+
+.mptk-dropdown__panel {
+  position: absolute;
+  left: 0;
+  right: 0;
+  background-color: var(--mptk-surface-1);
+  border-bottom-left-radius: var(--mptk-radius-md);
+  border-bottom-right-radius: var(--mptk-radius-md);
+  padding-top: var(--mptk-space-2);
+  padding-right: var(--mptk-space-3);
+  padding-bottom: var(--mptk-space-2);
+  padding-left: var(--mptk-space-3);
+}

package/dist/ui/state.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uiState = uiState;
+const singleton_js_1 = require("../runtime/singleton.cjs");
+const overlay_stack_js_1 = require("../runtime/overlay-stack.cjs");
+const notify_js_1 = require("../runtime/notify.cjs");
+const loading_slot_js_1 = require("../runtime/loading-slot.cjs");
+/**
+ * 全局唯一状态：用 runtime 的跨副本单例，保证命令式 API 与 <OverlayHost />
+ * 在主包 / 分包各副本里看到的是同一份栈、同一条通知队列、同一个 loading 槽。
+ */
+function uiState() {
+    return (0, singleton_js_1.createSingleton)('ui', () => ({
+        overlays: (0, overlay_stack_js_1.createOverlayStack)(),
+        notices: (0, notify_js_1.createNotifyCenter)(),
+        loading: (0, loading_slot_js_1.createLoadingSlot)(),
+        mounted: false,
+        loadingHandles: new Set(),
+    }));
+}

package/dist/ui/state.d.ts

@@ -0,0 +1,25 @@
+import type { OverlayStack } from '../runtime/overlay-stack.js';
+import type { NotifyCenter } from '../runtime/notify.js';
+import type { LoadingSlot } from '../runtime/loading-slot.js';
+/** 弹窗条目的载荷：命令式 API 只把待渲染数据推进栈，resolve 由 <OverlayHost /> 调用。 */
+export interface DialogPayload {
+    readonly kind: 'alert' | 'confirm';
+    readonly title: string | undefined;
+    readonly message: string;
+    readonly confirmText: string;
+    readonly cancelText: string;
+    readonly resolve: (confirmed: boolean) => void;
+}
+export interface UIState {
+    readonly overlays: OverlayStack<DialogPayload>;
+    readonly notices: NotifyCenter;
+    readonly loading: LoadingSlot;
+    /** 宿主是否已挂载 <OverlayHost />；命令式 API 靠它判定开发者契约。 */
+    mounted: boolean;
+    readonly loadingHandles: Set<number>;
+}
+/**
+ * 全局唯一状态：用 runtime 的跨副本单例，保证命令式 API 与 <OverlayHost />
+ * 在主包 / 分包各副本里看到的是同一份栈、同一条通知队列、同一个 loading 槽。
+ */
+export declare function uiState(): UIState;

package/dist/ui/state.js

@@ -0,0 +1,17 @@
+import { createSingleton } from '../runtime/singleton.js';
+import { createOverlayStack } from '../runtime/overlay-stack.js';
+import { createNotifyCenter } from '../runtime/notify.js';
+import { createLoadingSlot } from '../runtime/loading-slot.js';
+/**
+ * 全局唯一状态：用 runtime 的跨副本单例，保证命令式 API 与 <OverlayHost />
+ * 在主包 / 分包各副本里看到的是同一份栈、同一条通知队列、同一个 loading 槽。
+ */
+export function uiState() {
+    return createSingleton('ui', () => ({
+        overlays: createOverlayStack(),
+        notices: createNotifyCenter(),
+        loading: createLoadingSlot(),
+        mounted: false,
+        loadingHandles: new Set(),
+    }));
+}

package/dist/utils/date.cjs

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatYmd = formatYmd;
+exports.formatClock = formatClock;
+exports.formatDateTime = formatDateTime;
+exports.formatDurationHms = formatDurationHms;
+exports.sameDay = sameDay;
+exports.overlaps = overlaps;
+exports.relativeTime = relativeTime;
+// 日期 / 时间格式化，全部走本机时区。解析失败一律返回 '—'，不抛、不编造时间。
+const i18n_js_1 = require("./i18n.cjs");
+const FALLBACK = '—';
+const MINUTE = 60000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+/** 字符串先试原生解析，再试 `-` → `/`（小程序 iOS 只认斜杠格式）。 */
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? new Date(value) : null;
+    if (typeof value !== 'string' || value.trim() === '')
+        return null;
+    let ms = Date.parse(value);
+    if (Number.isNaN(ms) && !value.includes('T'))
+        ms = Date.parse(value.replace(/-/g, '/'));
+    return Number.isNaN(ms) ? null : new Date(ms);
+}
+/** `YYYY-MM-DD`。 */
+function formatYmd(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+/** `HH:mm:ss`。 */
+function formatClock(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+/** `YYYY-MM-DD HH:mm`。 */
+function formatDateTime(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${formatYmd(d)} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+/** 时长：有小时 ⇒ `H:MM:SS`，不足 1 小时 ⇒ `MM:SS`；负数 / 非有限 ⇒ `—`。 */
+function formatDurationHms(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return FALLBACK;
+    const total = Math.round(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    return h > 0 ? `${h}:${pad2(m)}:${pad2(s)}` : `${pad2(m)}:${pad2(s)}`;
+}
+/** 两个时刻是否同一天（本机时区）；任一无效 ⇒ false。 */
+function sameDay(a, b) {
+    const x = toDate(a);
+    const y = toDate(b);
+    if (!x || !y)
+        return false;
+    return (x.getFullYear() === y.getFullYear() && x.getMonth() === y.getMonth() && x.getDate() === y.getDate());
+}
+/** 半开区间 `[aFrom, aTo)` 是否重叠；非有限数视为不重叠。 */
+function overlaps(aFrom, aTo, bFrom, bTo) {
+    if (![aFrom, aTo, bFrom, bTo].every(Number.isFinite))
+        return false;
+    return aFrom < bTo && bFrom < aTo;
+}
+/**
+ * 相对时间：过去 ⇒ `N 分钟前`，未来 ⇒ `N 分钟后`；超过 7 天回退 `formatYmd`。
+ * 文案走 i18n，宿主注册其他语言后即随之切换；解析失败 ⇒ `—`。
+ */
+function relativeTime(value, now = Date.now()) {
+    const target = toDate(value);
+    const base = toDate(now);
+    if (!target || !base)
+        return FALLBACK;
+    const diff = target.getTime() - base.getTime();
+    const abs = Math.abs(diff);
+    if (abs < MINUTE)
+        return (0, i18n_js_1.t)('relNow');
+    if (abs >= 7 * DAY)
+        return formatYmd(target);
+    const past = diff < 0;
+    if (abs < HOUR)
+        return (0, i18n_js_1.t)(past ? 'relMinutesAgo' : 'relMinutesLater', { n: Math.floor(abs / MINUTE) });
+    if (abs < DAY)
+        return (0, i18n_js_1.t)(past ? 'relHoursAgo' : 'relHoursLater', { n: Math.floor(abs / HOUR) });
+    return (0, i18n_js_1.t)(past ? 'relDaysAgo' : 'relDaysLater', { n: Math.floor(abs / DAY) });
+}

package/dist/utils/date.d.ts

@@ -0,0 +1,18 @@
+export type DateLike = Date | number | string;
+/** `YYYY-MM-DD`。 */
+export declare function formatYmd(value: DateLike): string;
+/** `HH:mm:ss`。 */
+export declare function formatClock(value: DateLike): string;
+/** `YYYY-MM-DD HH:mm`。 */
+export declare function formatDateTime(value: DateLike): string;
+/** 时长：有小时 ⇒ `H:MM:SS`，不足 1 小时 ⇒ `MM:SS`；负数 / 非有限 ⇒ `—`。 */
+export declare function formatDurationHms(ms: number): string;
+/** 两个时刻是否同一天（本机时区）；任一无效 ⇒ false。 */
+export declare function sameDay(a: DateLike, b: DateLike): boolean;
+/** 半开区间 `[aFrom, aTo)` 是否重叠；非有限数视为不重叠。 */
+export declare function overlaps(aFrom: number, aTo: number, bFrom: number, bTo: number): boolean;
+/**
+ * 相对时间：过去 ⇒ `N 分钟前`，未来 ⇒ `N 分钟后`；超过 7 天回退 `formatYmd`。
+ * 文案走 i18n，宿主注册其他语言后即随之切换；解析失败 ⇒ `—`。
+ */
+export declare function relativeTime(value: DateLike, now?: DateLike): string;

package/dist/utils/date.js

@@ -0,0 +1,89 @@
+// 日期 / 时间格式化，全部走本机时区。解析失败一律返回 '—'，不抛、不编造时间。
+import { t } from './i18n.js';
+const FALLBACK = '—';
+const MINUTE = 60000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+/** 字符串先试原生解析，再试 `-` → `/`（小程序 iOS 只认斜杠格式）。 */
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? new Date(value) : null;
+    if (typeof value !== 'string' || value.trim() === '')
+        return null;
+    let ms = Date.parse(value);
+    if (Number.isNaN(ms) && !value.includes('T'))
+        ms = Date.parse(value.replace(/-/g, '/'));
+    return Number.isNaN(ms) ? null : new Date(ms);
+}
+/** `YYYY-MM-DD`。 */
+export function formatYmd(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+/** `HH:mm:ss`。 */
+export function formatClock(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+/** `YYYY-MM-DD HH:mm`。 */
+export function formatDateTime(value) {
+    const d = toDate(value);
+    if (!d)
+        return FALLBACK;
+    return `${formatYmd(d)} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+/** 时长：有小时 ⇒ `H:MM:SS`，不足 1 小时 ⇒ `MM:SS`；负数 / 非有限 ⇒ `—`。 */
+export function formatDurationHms(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return FALLBACK;
+    const total = Math.round(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    return h > 0 ? `${h}:${pad2(m)}:${pad2(s)}` : `${pad2(m)}:${pad2(s)}`;
+}
+/** 两个时刻是否同一天（本机时区）；任一无效 ⇒ false。 */
+export function sameDay(a, b) {
+    const x = toDate(a);
+    const y = toDate(b);
+    if (!x || !y)
+        return false;
+    return (x.getFullYear() === y.getFullYear() && x.getMonth() === y.getMonth() && x.getDate() === y.getDate());
+}
+/** 半开区间 `[aFrom, aTo)` 是否重叠；非有限数视为不重叠。 */
+export function overlaps(aFrom, aTo, bFrom, bTo) {
+    if (![aFrom, aTo, bFrom, bTo].every(Number.isFinite))
+        return false;
+    return aFrom < bTo && bFrom < aTo;
+}
+/**
+ * 相对时间：过去 ⇒ `N 分钟前`，未来 ⇒ `N 分钟后`；超过 7 天回退 `formatYmd`。
+ * 文案走 i18n，宿主注册其他语言后即随之切换；解析失败 ⇒ `—`。
+ */
+export function relativeTime(value, now = Date.now()) {
+    const target = toDate(value);
+    const base = toDate(now);
+    if (!target || !base)
+        return FALLBACK;
+    const diff = target.getTime() - base.getTime();
+    const abs = Math.abs(diff);
+    if (abs < MINUTE)
+        return t('relNow');
+    if (abs >= 7 * DAY)
+        return formatYmd(target);
+    const past = diff < 0;
+    if (abs < HOUR)
+        return t(past ? 'relMinutesAgo' : 'relMinutesLater', { n: Math.floor(abs / MINUTE) });
+    if (abs < DAY)
+        return t(past ? 'relHoursAgo' : 'relHoursLater', { n: Math.floor(abs / HOUR) });
+    return t(past ? 'relDaysAgo' : 'relDaysLater', { n: Math.floor(abs / DAY) });
+}

package/dist/utils/i18n.cjs

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLocale = getLocale;
+exports.setLocale = setLocale;
+exports.registerMessages = registerMessages;
+exports.t = t;
+// 唯一可变状态是语言注册表。默认语言是唯一静态引入的语言包；
+// 其他语言由宿主按需加载后 registerMessages 注入，库入口绝不静态引入全量语言包。
+const messages_zh_js_1 = require("./messages.zh.cjs");
+const DEFAULT_LOCALE = 'zh-CN';
+const registry = new Map([[DEFAULT_LOCALE, messages_zh_js_1.ZH_CN]]);
+let currentLocale = DEFAULT_LOCALE;
+function getLocale() {
+    return currentLocale;
+}
+/** 未注册的语言回落默认中文，不抛。 */
+function setLocale(locale) {
+    currentLocale = registry.has(locale) ? locale : DEFAULT_LOCALE;
+}
+/** 宿主按需加载语言包后注入；重复注册按 key 合并，不覆盖已有条目。 */
+function registerMessages(locale, messages) {
+    const existing = registry.get(locale);
+    registry.set(locale, existing ? { ...existing, ...messages } : { ...messages });
+}
+/** 取当前语言 → 缺 key 回落中文 → 仍缺返回 key；{n} 插值；从不抛。 */
+function t(key, params) {
+    const template = registry.get(currentLocale)?.[key] ?? registry.get(DEFAULT_LOCALE)?.[key] ?? key;
+    if (!params)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (match, name) => Object.keys(params).includes(name) ? String(params[name]) : match);
+}

package/dist/utils/i18n.d.ts

@@ -0,0 +1,11 @@
+export type Locale = string;
+export type Messages = Record<string, string>;
+export type MessageParams = Record<string, string | number>;
+export type Translate = (key: string, params?: MessageParams) => string;
+export declare function getLocale(): Locale;
+/** 未注册的语言回落默认中文，不抛。 */
+export declare function setLocale(locale: Locale): void;
+/** 宿主按需加载语言包后注入；重复注册按 key 合并，不覆盖已有条目。 */
+export declare function registerMessages(locale: Locale, messages: Messages): void;
+/** 取当前语言 → 缺 key 回落中文 → 仍缺返回 key；{n} 插值；从不抛。 */
+export declare function t(key: string, params?: MessageParams): string;

package/dist/utils/i18n.js

@@ -0,0 +1,25 @@
+// 唯一可变状态是语言注册表。默认语言是唯一静态引入的语言包；
+// 其他语言由宿主按需加载后 registerMessages 注入，库入口绝不静态引入全量语言包。
+import { ZH_CN } from './messages.zh.js';
+const DEFAULT_LOCALE = 'zh-CN';
+const registry = new Map([[DEFAULT_LOCALE, ZH_CN]]);
+let currentLocale = DEFAULT_LOCALE;
+export function getLocale() {
+    return currentLocale;
+}
+/** 未注册的语言回落默认中文，不抛。 */
+export function setLocale(locale) {
+    currentLocale = registry.has(locale) ? locale : DEFAULT_LOCALE;
+}
+/** 宿主按需加载语言包后注入；重复注册按 key 合并，不覆盖已有条目。 */
+export function registerMessages(locale, messages) {
+    const existing = registry.get(locale);
+    registry.set(locale, existing ? { ...existing, ...messages } : { ...messages });
+}
+/** 取当前语言 → 缺 key 回落中文 → 仍缺返回 key；{n} 插值；从不抛。 */
+export function t(key, params) {
+    const template = registry.get(currentLocale)?.[key] ?? registry.get(DEFAULT_LOCALE)?.[key] ?? key;
+    if (!params)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (match, name) => Object.keys(params).includes(name) ? String(params[name]) : match);
+}

package/dist/utils/index.cjs

@@ -1,2 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMessages = exports.t = exports.setLocale = exports.getLocale = exports.crumbsOf = exports.extOf = exports.parentOf = exports.joinPath = exports.clamp = exports.formatCount = exports.formatBytes = exports.baseNameOf = exports.truncateBytes = exports.safeTrim = exports.overlaps = exports.sameDay = exports.relativeTime = exports.formatDurationHms = exports.formatDateTime = exports.formatClock = exports.formatYmd = void 0;
+// utils 层单点出口：只做具名 re-export，不含实现。
+var date_js_1 = require("./date.cjs");
+Object.defineProperty(exports, "formatYmd", { enumerable: true, get: function () { return date_js_1.formatYmd; } });
+Object.defineProperty(exports, "formatClock", { enumerable: true, get: function () { return date_js_1.formatClock; } });
+Object.defineProperty(exports, "formatDateTime", { enumerable: true, get: function () { return date_js_1.formatDateTime; } });
+Object.defineProperty(exports, "formatDurationHms", { enumerable: true, get: function () { return date_js_1.formatDurationHms; } });
+Object.defineProperty(exports, "relativeTime", { enumerable: true, get: function () { return date_js_1.relativeTime; } });
+Object.defineProperty(exports, "sameDay", { enumerable: true, get: function () { return date_js_1.sameDay; } });
+Object.defineProperty(exports, "overlaps", { enumerable: true, get: function () { return date_js_1.overlaps; } });
+var string_js_1 = require("./string.cjs");
+Object.defineProperty(exports, "safeTrim", { enumerable: true, get: function () { return string_js_1.safeTrim; } });
+Object.defineProperty(exports, "truncateBytes", { enumerable: true, get: function () { return string_js_1.truncateBytes; } });
+Object.defineProperty(exports, "baseNameOf", { enumerable: true, get: function () { return string_js_1.baseNameOf; } });
+var number_js_1 = require("./number.cjs");
+Object.defineProperty(exports, "formatBytes", { enumerable: true, get: function () { return number_js_1.formatBytes; } });
+Object.defineProperty(exports, "formatCount", { enumerable: true, get: function () { return number_js_1.formatCount; } });
+Object.defineProperty(exports, "clamp", { enumerable: true, get: function () { return number_js_1.clamp; } });
+var path_js_1 = require("./path.cjs");
+Object.defineProperty(exports, "joinPath", { enumerable: true, get: function () { return path_js_1.joinPath; } });
+Object.defineProperty(exports, "parentOf", { enumerable: true, get: function () { return path_js_1.parentOf; } });
+Object.defineProperty(exports, "extOf", { enumerable: true, get: function () { return path_js_1.extOf; } });
+Object.defineProperty(exports, "crumbsOf", { enumerable: true, get: function () { return path_js_1.crumbsOf; } });
+var i18n_js_1 = require("./i18n.cjs");
+Object.defineProperty(exports, "getLocale", { enumerable: true, get: function () { return i18n_js_1.getLocale; } });
+Object.defineProperty(exports, "setLocale", { enumerable: true, get: function () { return i18n_js_1.setLocale; } });
+Object.defineProperty(exports, "t", { enumerable: true, get: function () { return i18n_js_1.t; } });
+Object.defineProperty(exports, "registerMessages", { enumerable: true, get: function () { return i18n_js_1.registerMessages; } });

package/dist/utils/index.d.ts

@@ -1 +1,5 @@
-export {};
+export { formatYmd, formatClock, formatDateTime, formatDurationHms, relativeTime, sameDay, overlaps, type DateLike, } from './date.js';
+export { safeTrim, truncateBytes, baseNameOf } from './string.js';
+export { formatBytes, formatCount, clamp } from './number.js';
+export { joinPath, parentOf, extOf, crumbsOf } from './path.js';
+export { getLocale, setLocale, t, registerMessages, type Locale, type Messages, type MessageParams, type Translate, } from './i18n.js';

package/dist/utils/index.js

@@ -1 +1,6 @@
-export {};
+// utils 层单点出口：只做具名 re-export，不含实现。
+export { formatYmd, formatClock, formatDateTime, formatDurationHms, relativeTime, sameDay, overlaps, } from './date.js';
+export { safeTrim, truncateBytes, baseNameOf } from './string.js';
+export { formatBytes, formatCount, clamp } from './number.js';
+export { joinPath, parentOf, extOf, crumbsOf } from './path.js';
+export { getLocale, setLocale, t, registerMessages, } from './i18n.js';

package/dist/utils/messages.zh.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZH_CN = void 0;
+// 默认中文极小字典：只收 utils 自己要吐的文案；界面文案由宿主自管。
+exports.ZH_CN = {
+    relNow: '刚刚',
+    relMinutesAgo: '{n} 分钟前',
+    relHoursAgo: '{n} 小时前',
+    relDaysAgo: '{n} 天前',
+    relMinutesLater: '{n} 分钟后',
+    relHoursLater: '{n} 小时后',
+    relDaysLater: '{n} 天后',
+};

package/dist/utils/messages.zh.d.ts

@@ -0,0 +1 @@
+export declare const ZH_CN: Record<string, string>;

package/dist/utils/messages.zh.js

@@ -0,0 +1,10 @@
+// 默认中文极小字典：只收 utils 自己要吐的文案；界面文案由宿主自管。
+export const ZH_CN = {
+    relNow: '刚刚',
+    relMinutesAgo: '{n} 分钟前',
+    relHoursAgo: '{n} 小时前',
+    relDaysAgo: '{n} 天前',
+    relMinutesLater: '{n} 分钟后',
+    relHoursLater: '{n} 小时后',
+    relDaysLater: '{n} 天后',
+};

package/dist/utils/number.cjs

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBytes = formatBytes;
+exports.formatCount = formatCount;
+exports.clamp = clamp;
+const FALLBACK = '—';
+/** 字节数 → 人话（`12 KB` / `3.4 MB`）；0 / 负数 / 非有限 ⇒ `—`。 */
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return FALLBACK;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value >= 10 ? String(Math.round(value)) : value.toFixed(1)} ${units[unit]}`;
+}
+/** 计数的大众格式：≥1K 用 K、≥1M 用 M（`1234` → `1.2K`）。 */
+function formatCount(n) {
+    if (!Number.isFinite(n))
+        return FALLBACK;
+    const trim = (v) => Math.abs(v) >= 100 ? String(Math.round(v)) : v.toFixed(1).replace(/\.0$/, '');
+    if (Math.abs(n) >= 1000000)
+        return `${trim(n / 1000000)}M`;
+    if (Math.abs(n) >= 1000)
+        return `${trim(n / 1000)}K`;
+    return String(n);
+}
+/** 夹到 `[min, max]`；非有限值或 min > max 时返回 min，不抛。 */
+function clamp(value, min, max) {
+    if (!Number.isFinite(value) || !Number.isFinite(min) || !Number.isFinite(max) || min > max)
+        return min;
+    return Math.min(Math.max(value, min), max);
+}

package/dist/utils/number.d.ts

@@ -0,0 +1,6 @@
+/** 字节数 → 人话（`12 KB` / `3.4 MB`）；0 / 负数 / 非有限 ⇒ `—`。 */
+export declare function formatBytes(bytes: number): string;
+/** 计数的大众格式：≥1K 用 K、≥1M 用 M（`1234` → `1.2K`）。 */
+export declare function formatCount(n: number): string;
+/** 夹到 `[min, max]`；非有限值或 min > max 时返回 min，不抛。 */
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/utils/number.js

@@ -0,0 +1,33 @@
+const FALLBACK = '—';
+/** 字节数 → 人话（`12 KB` / `3.4 MB`）；0 / 负数 / 非有限 ⇒ `—`。 */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return FALLBACK;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value >= 10 ? String(Math.round(value)) : value.toFixed(1)} ${units[unit]}`;
+}
+/** 计数的大众格式：≥1K 用 K、≥1M 用 M（`1234` → `1.2K`）。 */
+export function formatCount(n) {
+    if (!Number.isFinite(n))
+        return FALLBACK;
+    const trim = (v) => Math.abs(v) >= 100 ? String(Math.round(v)) : v.toFixed(1).replace(/\.0$/, '');
+    if (Math.abs(n) >= 1000000)
+        return `${trim(n / 1000000)}M`;
+    if (Math.abs(n) >= 1000)
+        return `${trim(n / 1000)}K`;
+    return String(n);
+}
+/** 夹到 `[min, max]`；非有限值或 min > max 时返回 min，不抛。 */
+export function clamp(value, min, max) {
+    if (!Number.isFinite(value) || !Number.isFinite(min) || !Number.isFinite(max) || min > max)
+        return min;
+    return Math.min(Math.max(value, min), max);
+}

package/dist/utils/path.cjs

@@ -0,0 +1,33 @@
+"use strict";
+// 纯路径方法：只做字符串切分 / 拼接，不碰宿主、不依赖 React / DOM。
+// 约定：POSIX `/` 分隔；空串 `''` 表示根。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinPath = joinPath;
+exports.parentOf = parentOf;
+exports.extOf = extOf;
+exports.crumbsOf = crumbsOf;
+/** 拼接子路径，去掉 dir 尾斜杠与 name 首斜杠，避免多余斜杠。 */
+function joinPath(dir, name) {
+    const base = dir.replace(/\/+$/, '');
+    const leaf = name.replace(/^\/+/, '');
+    if (base === '')
+        return leaf;
+    return leaf === '' ? base : `${base}/${leaf}`;
+}
+/** 父目录（无父 = 空串，表示根）；先剔尾斜杠，否则 `a/b/` 会返回 `a/b`。 */
+function parentOf(path) {
+    const trimmed = path.replace(/\/+$/, '');
+    const cut = trimmed.lastIndexOf('/');
+    return cut < 0 ? '' : trimmed.slice(0, cut);
+}
+/** 扩展名（小写、不含点）；无扩展名返回 `''`；忽略 `?` / `#` 之后部分。 */
+function extOf(path) {
+    const clean = path.split(/[?#]/)[0];
+    const name = clean.slice(clean.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? '' : name.slice(dot + 1).toLowerCase();
+}
+/** 路径分段（面包屑用）：`a/b/c` ⇒ `['a','b','c']`。 */
+function crumbsOf(path) {
+    return path.split('/').filter((segment) => segment !== '');
+}

package/dist/utils/path.d.ts

@@ -0,0 +1,8 @@
+/** 拼接子路径，去掉 dir 尾斜杠与 name 首斜杠，避免多余斜杠。 */
+export declare function joinPath(dir: string, name: string): string;
+/** 父目录（无父 = 空串，表示根）；先剔尾斜杠，否则 `a/b/` 会返回 `a/b`。 */
+export declare function parentOf(path: string): string;
+/** 扩展名（小写、不含点）；无扩展名返回 `''`；忽略 `?` / `#` 之后部分。 */
+export declare function extOf(path: string): string;
+/** 路径分段（面包屑用）：`a/b/c` ⇒ `['a','b','c']`。 */
+export declare function crumbsOf(path: string): string[];

package/dist/utils/path.js

@@ -0,0 +1,27 @@
+// 纯路径方法：只做字符串切分 / 拼接，不碰宿主、不依赖 React / DOM。
+// 约定：POSIX `/` 分隔；空串 `''` 表示根。
+/** 拼接子路径，去掉 dir 尾斜杠与 name 首斜杠，避免多余斜杠。 */
+export function joinPath(dir, name) {
+    const base = dir.replace(/\/+$/, '');
+    const leaf = name.replace(/^\/+/, '');
+    if (base === '')
+        return leaf;
+    return leaf === '' ? base : `${base}/${leaf}`;
+}
+/** 父目录（无父 = 空串，表示根）；先剔尾斜杠，否则 `a/b/` 会返回 `a/b`。 */
+export function parentOf(path) {
+    const trimmed = path.replace(/\/+$/, '');
+    const cut = trimmed.lastIndexOf('/');
+    return cut < 0 ? '' : trimmed.slice(0, cut);
+}
+/** 扩展名（小写、不含点）；无扩展名返回 `''`；忽略 `?` / `#` 之后部分。 */
+export function extOf(path) {
+    const clean = path.split(/[?#]/)[0];
+    const name = clean.slice(clean.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? '' : name.slice(dot + 1).toLowerCase();
+}
+/** 路径分段（面包屑用）：`a/b/c` ⇒ `['a','b','c']`。 */
+export function crumbsOf(path) {
+    return path.split('/').filter((segment) => segment !== '');
+}