@aithe/aithe-ui 26.2.3 → 26.3.2

package/dist/core/datahub/types.js

@@ -0,0 +1,31 @@
+/**
+ * @file DataHub 类型定义 / DataHub Type Definitions
+ * @description 定义 DataHub 数据中间层的所有标准类型，包括 APIStyle 业务协议相关类型。
+ *
+ *              核心设计原则：
+ *              - DataHub 只负责 HTTP 传输层（请求/响应），不关心业务协议
+ *              - 业务协议（如 code/message/data 结构）由 APIStyle 封装
+ *              - 适配器只做 JSON 解析，不做业务语义判断
+ *
+ *              Defines all standard types for the DataHub middleware layer,
+ *              including APIStyle business protocol types.
+ */
+/**
+ * DataHub 统一错误类 / DataHub Unified Error Class
+ * @description 封装网络错误、中断错误、HTTP 错误等，提供统一的错误结构。
+ *              包含错误码、链路追踪 ID、HTTP 状态码和请求 URL 等信息。
+ *              Encapsulates network errors, abort errors, HTTP errors, etc.,
+ *              providing a unified error structure with error code, trace ID,
+ *              HTTP status code, and request URL.
+ */
+export class DataHubError extends Error {
+    constructor(detail) {
+        super(detail.message);
+        this.name = 'DataHubError';
+        this.code = detail.code;
+        this.trace = detail.trace;
+        this.status = detail.status;
+        this.url = detail.url;
+        this.data = detail.data;
+    }
+}

package/dist/core/datahub/utils/cache.js

@@ -0,0 +1,55 @@
+/**
+ * @file 内存缓存工具 / In-Memory Cache Utility
+ * @description 为查询类请求提供基于 TTL（Time-To-Live）的内存缓存。
+ *              缓存键由 URL + 请求数据序列化生成，确保相同参数命中同一缓存。
+ *              过期条目在读取时惰性删除，无需定时清理。
+ *              Provides TTL (Time-To-Live) based in-memory caching for query requests.
+ *              Cache keys are generated from URL + serialized request data, ensuring identical
+ *              parameters hit the same cache entry. Expired entries are lazily evicted on read,
+ *              requiring no periodic cleanup.
+ */
+import { buildKey } from './common';
+/** 内存缓存存储，键为 "url::data" 序列化字符串 / In-memory store, keyed by "url::data" serialized string */
+const store = new Map();
+/**
+ * 读取缓存 / Read from cache
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 缓存命中返回数据，未命中或已过期返回 null / Cached data on hit, null on miss or expiration
+ */
+export function cacheGet(url, data) {
+    const key = buildKey(url, data);
+    const entry = store.get(key);
+    if (!entry)
+        return null;
+    // 惰性删除：已过期的条目在读取时清除 / Lazy eviction: expired entries are removed on read
+    if (Date.now() > entry.expireAt) {
+        store.delete(key);
+        return null;
+    }
+    return entry.data;
+}
+/**
+ * 写入缓存 / Write to cache
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @param value - 要缓存的数据 / Data to cache
+ * @param ttl - 缓存有效期（毫秒）/ Cache TTL in milliseconds
+ */
+export function cacheSet(url, data, value, ttl) {
+    const key = buildKey(url, data);
+    store.set(key, { data: value, expireAt: Date.now() + ttl });
+}
+/**
+ * 删除指定缓存条目 / Delete a specific cache entry
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 是否成功删除 / Whether the entry was successfully deleted
+ */
+export function cacheDelete(url, data) {
+    return store.delete(buildKey(url, data));
+}
+/** 清空所有缓存 / Clear all cache entries */
+export function cacheClear() {
+    store.clear();
+}

package/dist/core/datahub/utils/common.js

@@ -0,0 +1,23 @@
+/**
+ * @file 公共工具函数 / Common Utility Functions
+ * @description 提供 DataHub 内部各模块共享的工具函数，
+ *              避免在 cache、dedup、idempotent 等模块中重复实现。
+ *              当前提供 buildKey 函数，用于生成标准化的缓存/去重/幂等键。
+ *              Provides shared utility functions for DataHub internal modules,
+ *              avoiding duplicate implementations across cache, dedup, idempotent, etc.
+ *              Currently provides buildKey for generating standardized cache/dedup/idempotent keys.
+ */
+/**
+ * 生成标准化的键 / Generate a standardized key
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 唯一键，格式为 "url::JSON(data)" / Unique key in format "url::JSON(data)"
+ * @description 用于缓存、去重、幂等防护等模块的键生成，
+ *              确保相同 URL + 相同数据命中同一键。
+ *              Used for key generation in cache, dedup, idempotent guard modules,
+ *              ensuring identical URL + data hit the same key.
+ */
+export function buildKey(url, data) {
+    const serialized = data === undefined ? 'null' : JSON.stringify(data);
+    return `${url}::${serialized}`;
+}

package/dist/core/datahub/utils/dedup.d.ts

@@ -22,7 +22,7 @@
  * ]);
  * // r1 === r2，共享同一结果 / r1 === r2, sharing the same result
  */
-export declare function dedupTrack<T>(url: string, data: unknown | undefined, factory: () => Promise<T>): Promise<T>;
+export declare function dedupTrack<T>(url: string, data: unknown, factory: () => Promise<T>): Promise<T>;
 /** 清空所有去重记录（一般用于测试或重置状态）/ Clear all dedup records (typically for testing or state reset) */
 export declare function dedupClear(): void;
 //# sourceMappingURL=dedup.d.ts.map

package/dist/core/datahub/utils/dedup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../../../../src/core/datahub/utils/dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../../../../src/core/datahub/utils/dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/core/datahub/utils/dedup.js

@@ -0,0 +1,52 @@
+/**
+ * @file 请求去重工具 / Request Deduplication Utility
+ * @description 对查询类请求进行去重处理：当多个相同请求并发时，
+ *              只实际发出一次请求，所有调用方共享同一个 Promise 结果。
+ *              请求完成后自动清理，不影响后续正常请求。
+ *              Deduplicates query requests: when multiple identical requests are concurrent,
+ *              only one actual request is sent, and all callers share the same Promise result.
+ *              Pending entries are automatically cleaned up after completion, not affecting subsequent requests.
+ */
+import { buildKey } from './common';
+/** 正在进行的请求映射，键为 "url::data"，值为进行中的 Promise / In-flight request map, keyed by "url::data", valued by pending Promise */
+const pending = new Map();
+/**
+ * 去重追踪：相同请求并发时复用已有 Promise / Dedup tracking: reuse existing Promise for concurrent identical requests
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @param factory - 实际发起请求的工厂函数 / Factory function that performs the actual request
+ * @returns 请求结果 Promise（可能是新建的，也可能是复用的）/ Request result Promise (may be new or reused)
+ *
+ * @example
+ * // 两个并发调用只会发出一次实际请求 / Two concurrent calls result in only one actual request
+ * const [r1, r2] = await Promise.all([
+ *   dedupTrack('/order/query', { id: 1 }, () => fetch(...)),
+ *   dedupTrack('/order/query', { id: 1 }, () => fetch(...)),
+ * ]);
+ * // r1 === r2，共享同一结果 / r1 === r2, sharing the same result
+ */
+export function dedupTrack(url, data, factory) {
+    const key = buildKey(url, data);
+    // 已有相同请求正在进行，直接复用 / Same request already in-flight, reuse directly
+    const existing = pending.get(key);
+    if (existing)
+        return existing;
+    // 首次请求，创建 Promise 并注册 / First request, create Promise and register
+    const promise = factory()
+        .then((result) => {
+        // 请求成功后清理注册表 / Clean up registry after success
+        pending.delete(key);
+        return result;
+    })
+        .catch((err) => {
+        // 请求失败也要清理，避免后续请求被永久阻塞 / Clean up on failure too, preventing permanent blocking
+        pending.delete(key);
+        throw err;
+    });
+    pending.set(key, promise);
+    return promise;
+}
+/** 清空所有去重记录（一般用于测试或重置状态）/ Clear all dedup records (typically for testing or state reset) */
+export function dedupClear() {
+    pending.clear();
+}

package/dist/core/datahub/utils/idempotent.js

@@ -0,0 +1,61 @@
+/**
+ * @file 幂等防护工具 / Idempotent Guard Utility
+ * @description 对提交类请求进行幂等防护：在请求未完成前，阻止相同参数的重复提交。
+ *              与去重（dedup）不同，幂等防护是"拒绝"而非"复用"——
+ *              提交类请求不能简单复用结果，必须明确阻止重复操作。
+ *              Provides idempotent protection for submit requests: blocks duplicate submissions
+ *              with the same parameters while a request is still in-flight.
+ *              Unlike dedup, the idempotent guard "rejects" rather than "reuses" —
+ *              submit requests cannot simply reuse results; duplicate operations must be explicitly blocked.
+ */
+import { buildKey } from './common';
+import { DataHubError } from '../../datahub/types';
+/** 幂等锁映射，键为 "url::data"，值为进行中的 Promise / Idempotent lock map, keyed by "url::data", valued by in-flight Promise */
+const idempotentLocks = new Map();
+/**
+ * 幂等防护：阻止重复提交 / Idempotent guard: block duplicate submissions
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @param factory - 实际发起请求的工厂函数 / Factory function that performs the actual request
+ * @returns 请求结果 Promise / Request result Promise
+ * @throws 重复提交时直接 reject，提示已被拦截 / Rejects on duplicate submission with a blocked message
+ *
+ * @example
+ * // 用户快速双击提交按钮 / User double-clicks the submit button
+ * try {
+ *   await idempotentGuard('/order/pay', { orderId: '1' }, () => fetch(...));
+ * } catch (e) {
+ *   // 第二次调用会被拦截，抛出 "duplicate submit blocked" 错误
+ *   // The second call is blocked, throwing a "duplicate submit blocked" error
+ * }
+ */
+export function idempotentGuard(url, data, factory) {
+    const key = buildKey(url, data);
+    // 已有相同请求正在进行，直接拒绝（而非复用）/ Same request in-flight, reject directly (not reuse)
+    const existing = idempotentLocks.get(key);
+    if (existing) {
+        return Promise.reject(new DataHubError({
+            code: 'DuplicateSubmit',
+            message: `[DataHub] Idempotent guard: duplicate submit blocked for ${url}`,
+            url
+        }));
+    }
+    // 首次提交，加锁并执行 / First submission, acquire lock and execute
+    const promise = factory()
+        .then((result) => {
+        // 请求完成后释放锁 / Release lock after completion
+        idempotentLocks.delete(key);
+        return result;
+    })
+        .catch((err) => {
+        // 请求失败也要释放锁，允许用户重试 / Release lock on failure too, allowing user retry
+        idempotentLocks.delete(key);
+        throw err;
+    });
+    idempotentLocks.set(key, promise);
+    return promise;
+}
+/** 清空所有幂等锁（一般用于测试或重置状态）/ Clear all idempotent locks (typically for testing or state reset) */
+export function idempotentClear() {
+    idempotentLocks.clear();
+}

package/dist/core/datahub/utils/is-query.js

@@ -0,0 +1,53 @@
+/**
+ * @file URL 查询动作识别 / URL Query Action Detection
+ * @description 根据 URL 最后一段路径判断请求是否为查询类动作。
+ *              识别关键词可配置，默认：query、list、get。
+ *              用于策略自动选择：查询类走缓存+去重，提交类走幂等防护。
+ *              Determines whether a request is a query action based on the last URL path segment.
+ *              Recognized keywords are configurable, defaulting to: query, list, get.
+ *              Used for automatic strategy selection: query → cache + dedup, submit → idempotent guard.
+ */
+/** 默认查询类动作关键词列表 / Default query action keyword list */
+const DEFAULT_QUERY_KEYWORDS = ['query', 'list', 'get'];
+/** 当前生效的查询关键词列表 / Currently active query keyword list */
+let queryKeywords = [...DEFAULT_QUERY_KEYWORDS];
+/**
+ * 设置查询类动作关键词 / Set query action keywords
+ * @param keywords - 自定义关键词列表，将替换默认列表 / Custom keyword list, replaces the default list
+ * @description 允许外部扩展或覆盖默认的查询关键词，
+ *              例如添加 "search"、"fetch" 等自定义查询动作。
+ *              Allows external extension or override of default query keywords,
+ *              e.g. adding "search", "fetch" as custom query actions.
+ *
+ * @example
+ * setQueryKeywords(['query', 'list', 'get', 'search', 'fetch']);
+ */
+export function setQueryKeywords(keywords) {
+    queryKeywords = keywords;
+}
+/**
+ * 获取当前查询关键词列表 / Get current query keyword list
+ * @returns 当前生效的关键词列表副本 / Copy of currently active keyword list
+ */
+export function getQueryKeywords() {
+    return [...queryKeywords];
+}
+/**
+ * 判断 URL 是否为查询类动作 / Determine if the URL represents a query action
+ * @param url - 请求地址，如 "/order/query"、"/user/list" / Request URL, e.g. "/order/query", "/user/list"
+ * @returns true 表示查询类动作，false 表示提交类动作 / true for query action, false for submit action
+ *
+ * @example
+ * isQueryAction('/order/query')   // true
+ * isQueryAction('/order/submit')  // false
+ * isQueryAction('/user/list')     // true
+ * isQueryAction('/order/pay')     // false
+ */
+export function isQueryAction(url) {
+    let cleaned = url;
+    while (cleaned.endsWith('/')) {
+        cleaned = cleaned.slice(0, -1);
+    }
+    const segment = cleaned.split('/').pop()?.toLowerCase() ?? '';
+    return queryKeywords.some((kw) => segment === kw || segment.startsWith(kw + '/'));
+}

package/dist/core/datahub/utils/loading.js

@@ -0,0 +1,78 @@
+/**
+ * @file 全局 Loading 状态管理 / Global Loading State Management
+ * @description 提供请求级别的 loading 状态追踪与订阅机制。
+ *              业务层可监听 loading 变化来控制 UI 中的加载指示器。
+ *              基于 URL 粒度管理，使用计数模式支持同一 URL 的多次并发请求叠加，
+ *              只有计数归零时才触发 loading=false 回调。
+ *              Provides request-level loading state tracking and subscription mechanism.
+ *              The business layer can listen for loading changes to control UI loading indicators.
+ *              Managed at URL granularity, using a counter model to support overlapping requests
+ *              for the same URL. Only triggers loading=false callback when the count reaches zero.
+ */
+/** 已注册的监听器集合 / Registered listener set */
+const listeners = new Set();
+/** 每个 URL 的并发请求计数 / Concurrent request count per URL */
+const counterMap = new Map();
+/**
+ * 标记请求开始 / Mark request as started
+ * @param url - 请求地址 / Request URL
+ * @description 计数 +1，首次从 0→1 时通知监听器 loading=true
+ *              Counter +1, notifies listeners loading=true on first transition 0→1
+ */
+export function loadingStart(url) {
+    const prev = counterMap.get(url) ?? 0;
+    counterMap.set(url, prev + 1);
+    if (prev === 0) {
+        for (const fn of listeners) {
+            fn(url, true);
+        }
+    }
+}
+/**
+ * 标记请求结束 / Mark request as ended
+ * @param url - 请求地址 / Request URL
+ * @description 计数 -1，归零时通知监听器 loading=false
+ *              Counter -1, notifies listeners loading=false when count reaches zero
+ */
+export function loadingEnd(url) {
+    const prev = counterMap.get(url) ?? 0;
+    if (prev <= 1) {
+        counterMap.delete(url);
+        if (prev === 1) {
+            for (const fn of listeners) {
+                fn(url, false);
+            }
+        }
+    }
+    else {
+        counterMap.set(url, prev - 1);
+    }
+}
+/**
+ * 查询指定 URL 是否正在加载 / Check if the specified URL is currently loading
+ * @param url - 请求地址 / Request URL
+ * @returns 是否正在加载 / Whether it is currently loading
+ */
+export function isLoading(url) {
+    return (counterMap.get(url) ?? 0) > 0;
+}
+/**
+ * 订阅 loading 状态变更 / Subscribe to loading state changes
+ * @param fn - 状态变更回调 / State change callback
+ * @returns 取消订阅函数 / Unsubscribe function
+ *
+ * @example
+ * const unsubscribe = onLoadingChange((url, loading) => {
+ *   if (url === '/order/query') {
+ *     setSpinnerVisible(loading);
+ *   }
+ * });
+ * // 组件卸载时取消订阅 / Unsubscribe on component unmount
+ * unsubscribe();
+ */
+export function onLoadingChange(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}

package/dist/core/filter/__tests__/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/core/filter/__tests__/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../../src/core/filter/__tests__/index.test.ts"],"names":[],"mappings":""}

package/dist/core/filter/__tests__/index.test.js

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vitest';
+import { AmountFilter, DateFilter, EmptyFilter, BytesFilter, TimeAgoFilter } from '../../filter/builtins';
+import { FilterFactory } from '../../filter/factory';
+import { filterFactory } from '../../filter/index';
+import { registerAitheLocale } from '../../../styles/i18n';
+import { en as enLocale } from '../../../styles/i18n/locales/en-US';
+beforeAll(() => {
+    registerAitheLocale('en-US', enLocale);
+});
+// --- AmountFilter ---
+describe('AmountFilter', () => {
+    const filter = new AmountFilter();
+    it('formats number to 2 decimal places', () => {
+        expect(filter.apply(123.4)).toBe('123.40');
+        expect(filter.apply(0)).toBe('0.00');
+        expect(filter.apply(100)).toBe('100.00');
+    });
+    it('parses numeric string', () => {
+        expect(filter.apply('123.456')).toBe('123.46');
+        expect(filter.apply('0')).toBe('0.00');
+    });
+    it('returns -- for null/undefined', () => {
+        expect(filter.apply(null)).toBe('--');
+        expect(filter.apply(undefined)).toBe('--');
+    });
+    it('returns -- for non-numeric string', () => {
+        expect(filter.apply('abc')).toBe('--');
+        expect(filter.apply('')).toBe('--');
+    });
+});
+// --- DateFilter ---
+describe('DateFilter', () => {
+    const filter = new DateFilter();
+    it('formats Date object with default format', () => {
+        const d = new Date(2024, 0, 15, 14, 30, 45);
+        expect(filter.apply(d)).toBe('2024-01-15 14:30:45');
+    });
+    it('formats with custom format', () => {
+        const d = new Date(2024, 0, 15);
+        expect(filter.apply(d, 'yyyy/MM/dd')).toBe('2024/01/15');
+        expect(filter.apply(d, 'MM-dd')).toBe('01-15');
+    });
+    it('parses timestamp (ms)', () => {
+        const ts = new Date(2024, 5, 1).getTime();
+        expect(filter.apply(ts, 'yyyy-MM-dd')).toBe('2024-06-01');
+    });
+    it('parses date string', () => {
+        expect(filter.apply('2024-01-15', 'yyyy/MM/dd')).toBe('2024/01/15');
+    });
+    it('returns -- for null/undefined/empty', () => {
+        expect(filter.apply(null)).toBe('--');
+        expect(filter.apply(undefined)).toBe('--');
+        expect(filter.apply('')).toBe('--');
+    });
+    it('returns -- for invalid date string', () => {
+        expect(filter.apply('not-a-date')).toBe('--');
+    });
+});
+// --- EmptyFilter ---
+describe('EmptyFilter', () => {
+    const filter = new EmptyFilter();
+    it('returns value as string for non-empty', () => {
+        expect(filter.apply('hello')).toBe('hello');
+        expect(filter.apply(0)).toBe('0');
+        expect(filter.apply(false)).toBe('false');
+    });
+    it('returns placeholder for null/undefined', () => {
+        expect(filter.apply(null)).toBe('--');
+        expect(filter.apply(undefined)).toBe('--');
+    });
+    it('returns placeholder for empty string', () => {
+        expect(filter.apply('')).toBe('--');
+    });
+    it('returns placeholder for NaN', () => {
+        expect(filter.apply(NaN)).toBe('--');
+    });
+    it('supports custom placeholder', () => {
+        expect(filter.apply(null, '-')).toBe('-');
+        expect(filter.apply('', 'N/A')).toBe('N/A');
+    });
+});
+// --- BytesFilter ---
+describe('BytesFilter', () => {
+    const filter = new BytesFilter();
+    it('formats bytes in IEC (1024) by default', () => {
+        expect(filter.apply(0)).toBe('0 B');
+        expect(filter.apply(500)).toBe('500 B');
+        expect(filter.apply(1024)).toBe('1.00 KiB');
+        expect(filter.apply(1536)).toBe('1.50 KiB');
+        expect(filter.apply(1048576)).toBe('1.00 MiB');
+        expect(filter.apply(1073741824)).toBe('1.00 GiB');
+    });
+    it('formats bytes in SI (1000)', () => {
+        expect(filter.apply(1000, '1000')).toBe('1.00 KB');
+        expect(filter.apply(1000000, '1000')).toBe('1.00 MB');
+        expect(filter.apply(1000000000, '1000')).toBe('1.00 GB');
+    });
+    it('returns -- for null/undefined', () => {
+        expect(filter.apply(null)).toBe('--');
+        expect(filter.apply(undefined)).toBe('--');
+    });
+    it('returns -- for negative values', () => {
+        expect(filter.apply(-1)).toBe('--');
+    });
+    it('returns -- for non-numeric string', () => {
+        expect(filter.apply('abc')).toBe('--');
+    });
+});
+// --- TimeAgoFilter ---
+describe('TimeAgoFilter', () => {
+    const filter = new TimeAgoFilter();
+    const now = Date.now();
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(now);
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('returns just now for < 60s', () => {
+        expect(filter.apply(now)).toBe('just now');
+        expect(filter.apply(now - 30_000)).toBe('just now');
+    });
+    it('returns minutes ago', () => {
+        expect(filter.apply(now - 120_000)).toBe('2 minutes ago');
+        expect(filter.apply(now - 3_600_000 + 1)).toBe('59 minutes ago');
+    });
+    it('returns hours ago', () => {
+        expect(filter.apply(now - 7_200_000)).toBe('2 hours ago');
+        expect(filter.apply(now - 86_400_000 + 1)).toBe('23 hours ago');
+    });
+    it('returns days ago', () => {
+        expect(filter.apply(now - 172_800_000)).toBe('2 days ago');
+        expect(filter.apply(now - 2_592_000_000 + 1)).toBe('29 days ago');
+    });
+    it('returns months ago', () => {
+        expect(filter.apply(now - 5_184_000_000)).toBe('2 months ago');
+        expect(filter.apply(now - 25_920_000_000)).toBe('10 months ago');
+    });
+    it('returns date for > 1 year', () => {
+        const past = new Date(now - 31_104_000_000 - 86_400_000);
+        const y = past.getFullYear();
+        const m = String(past.getMonth() + 1).padStart(2, '0');
+        const d = String(past.getDate()).padStart(2, '0');
+        expect(filter.apply(past.getTime())).toBe(`${y}-${m}-${d}`);
+    });
+    it('handles future times', () => {
+        expect(filter.apply(now + 120_000)).toBe('in 2 minutes');
+        expect(filter.apply(now + 7_200_000)).toBe('in 2 hours');
+        expect(filter.apply(now + 172_800_000)).toBe('in 2 days');
+        expect(filter.apply(now + 5_184_000_000)).toBe('in 2 months');
+    });
+    it('returns -- for null/undefined/empty', () => {
+        expect(filter.apply(null)).toBe('--');
+        expect(filter.apply(undefined)).toBe('--');
+        expect(filter.apply('')).toBe('--');
+    });
+    it('returns -- for invalid date string', () => {
+        expect(filter.apply('not-a-date')).toBe('--');
+    });
+});
+// --- FilterFactory ---
+describe('FilterFactory', () => {
+    it('registers built-in filters', () => {
+        const factory = new FilterFactory();
+        expect(factory.has('amount')).toBe(true);
+        expect(factory.has('date')).toBe(true);
+        expect(factory.has('empty')).toBe(true);
+        expect(factory.has('bytes')).toBe(true);
+        expect(factory.has('timeAgo')).toBe(true);
+    });
+    it('registers custom filter', () => {
+        const factory = new FilterFactory();
+        class UpperFilter {
+            apply(value) {
+                return value.toUpperCase();
+            }
+        }
+        factory.register('upper', UpperFilter);
+        expect(factory.has('upper')).toBe(true);
+        expect(factory.get('upper')?.apply('hello')).toBe('HELLO');
+    });
+    it('formats value with expression string', () => {
+        const factory = new FilterFactory();
+        expect(factory.format(123.4, 'amount')).toBe('123.40');
+        expect(factory.format(null, 'empty')).toBe('--');
+    });
+    it('formats value with chained expression', () => {
+        const factory = new FilterFactory();
+        expect(factory.format(null, 'empty | empty -')).toBe('--');
+    });
+    it('returns original value for unknown filter', () => {
+        const factory = new FilterFactory();
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        expect(factory.format('test', 'unknown')).toBe('test');
+        expect(warn).toHaveBeenCalled();
+        warn.mockRestore();
+    });
+    it('parses expression string', () => {
+        const factory = new FilterFactory();
+        expect(factory.parse('amount')).toEqual([{ name: 'amount', args: [] }]);
+        expect(factory.parse('date yyyy/MM/dd')).toEqual([{ name: 'date', args: ['yyyy/MM/dd'] }]);
+        expect(factory.parse('amount | empty')).toEqual([
+            { name: 'amount', args: [] },
+            { name: 'empty', args: [] },
+        ]);
+    });
+    it('stringifies expressions', () => {
+        const factory = new FilterFactory();
+        expect(factory.stringify([{ name: 'amount', args: [] }])).toBe('amount');
+        expect(factory.stringify([{ name: 'date', args: ['yyyy/MM/dd'] }])).toBe('date yyyy/MM/dd');
+        expect(factory.stringify([
+            { name: 'amount', args: [] },
+            { name: 'empty', args: [] },
+        ])).toBe('amount | empty');
+    });
+    it('names() returns registered filter names', () => {
+        const factory = new FilterFactory();
+        const names = factory.names();
+        expect(names).toContain('amount');
+        expect(names).toContain('date');
+    });
+});
+// --- filterFactory instance ---
+describe('filterFactory instance', () => {
+    it('is a FilterFactory instance with built-in filters', () => {
+        expect(filterFactory).toBeInstanceOf(FilterFactory);
+        expect(filterFactory.has('amount')).toBe(true);
+    });
+});