@pinnacle0/web-ui 0.3.22 → 0.3.23

package/src/internal/ExpirableLocalStorage.ts

@@ -0,0 +1,262 @@
+interface Data {
+    value: string;
+    expiryTimestamp: number;
+}
+
+/**
+ * an expirable local storage (Singleton)
+ */
+export class ExpirableLocalStorage {
+    private static readonly PREFIX = "@@EXPIRABLE/";
+    private static readonly TRUE = "TRUE";
+    private static readonly FALSE = "FALSE";
+    private static readonly DEFAULT_DATA_VALUE = {expiryTimestamp: 0, value: null};
+
+    private static instance: ExpirableLocalStorage;
+
+    private storage: Storage = window.localStorage;
+
+    /**
+     * get the ExpirableStorage instance
+     */
+    static getInstance() {
+        if (!ExpirableLocalStorage.instance) {
+            ExpirableLocalStorage.instance = new ExpirableLocalStorage();
+        }
+
+        return ExpirableLocalStorage.instance;
+    }
+
+    /**
+     * set boolean value
+     * @param key storage key
+     * @param value boolean value
+     * @param expiryTimestamp expiry timestamp
+     */
+    setBool(key: string, value: boolean, expiryTimestamp: number): void {
+        this.set(key, value ? ExpirableLocalStorage.TRUE : ExpirableLocalStorage.FALSE, expiryTimestamp);
+    }
+
+    /**
+     * set string
+     * @param key storage key
+     * @param value string value
+     * @param expiryTimestamp expiry timestamp
+     */
+    setString(key: string, value: string, expiryTimestamp: number): void {
+        this.set(key, value, expiryTimestamp);
+    }
+
+    /**
+     * set number
+     * @param key storage key
+     * @param value number value
+     * @param expiryTimestamp expiry timestamp
+     */
+    setNumber(key: string, value: number, expiryTimestamp: number): void {
+        this.set(key, value.toString(), expiryTimestamp);
+    }
+
+    /**
+     * set object
+     * @param key storage key
+     * @param item object
+     * @param expiryTimestamp expiry timestamp
+     */
+    setObject<T extends object>(key: string, item: T, expiryTimestamp: number): void {
+        this.set(key, JSON.stringify(item), expiryTimestamp);
+    }
+
+    /**
+     * get boolean value
+     * @param key storage key
+     * @param defaultValue default value
+     * @returns boolean value
+     */
+    getBool(key: string, defaultValue: boolean): boolean {
+        const transformer = (_: string) => (_ === ExpirableLocalStorage.TRUE ? true : _ === ExpirableLocalStorage.FALSE ? false : null);
+        return this.get(key, defaultValue, transformer);
+    }
+
+    /**
+     * get string value
+     * @param key storage key
+     * @param defaultValue default value
+     * @param validValues valid values
+     * @returns string value
+     */
+    getString<T extends string = string>(key: string, defaultValue: T, validValues?: readonly T[]): T {
+        const transformer = (_: string): T | null => {
+            const typedValue = _ as T;
+            return validValues ? (validValues.includes(typedValue) ? typedValue : null) : typedValue;
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    /**
+     * get number value
+     * @param key storage key
+     * @param defaultValue default value
+     * @param validator validator
+     * @returns number value
+     */
+    getNumber(key: string, defaultValue: number, validator?: number[] | ((value: number) => boolean)): number {
+        const transformer = (_: string): number | null => {
+            const numberedData = Number(_);
+            if (Number.isFinite(numberedData)) {
+                if (validator === undefined) {
+                    return numberedData;
+                } else if (typeof validator === "function") {
+                    if (validator(numberedData)) {
+                        return numberedData;
+                    }
+                } else {
+                    if (validator.includes(numberedData)) {
+                        return numberedData;
+                    }
+                }
+            }
+            return null;
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    /**
+     * get object value
+     * @param key storage key
+     * @param defaultValue default value
+     * @param validator validator
+     * @returns object value
+     */
+    getObject<T extends object>(key: string, defaultValue: T, validator: (item: object) => boolean): T {
+        const transformer = (_: string): T | null => {
+            try {
+                const obj: object = JSON.parse(_);
+                if (validator(obj)) {
+                    return obj as T;
+                } else {
+                    return null;
+                }
+            } catch (e) {
+                return null;
+            }
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    /**
+     * get the raw localstorage data
+     * @param key storage key
+     * @returns raw data
+     */
+    getRaw(key: string): string | null {
+        try {
+            return this.storage.getItem(this.canonicalKey(key));
+        } catch (e) {
+            return null;
+        }
+    }
+
+    /**
+     * The ExpirableStorage's constructor should always be private to prevent direct
+     * construction calls with the `new` operator.
+     */
+    private constructor() {}
+
+    /**
+     * get current timestamp
+     * @returns current timestamp
+     */
+    private now(): number {
+        return new Date().getTime();
+    }
+
+    /**
+     * get value
+     * @param key storage key
+     * @param defaultValue
+     * @param transformer
+     * @returns
+     */
+    private get<T extends string | number | boolean | object>(key: string, defaultValue: T, transformer: (value: string) => T | null) {
+        try {
+            this.prune();
+            const {value} = this.getData(this.canonicalKey(key));
+
+            if (value !== null) {
+                return transformer(value) || defaultValue;
+            }
+
+            return defaultValue;
+        } catch (e) {
+            return defaultValue;
+        }
+    }
+
+    /**
+     * set value
+     * @param key storage key
+     * @param value storage value
+     * @param expiryTimestamp The "expiryTimestamp" (expiration time) claim identifies the expiration time on or after which the value MUST NOT be accepted for processing. The processing of the "expiryTimestamp" claim requires that the current date/time MUST be before the expiration date/time listed in the "expiryTimestamp" claim.
+     */
+    private set(key: string, value: string, expiryTimestamp: number): void {
+        try {
+            this.setData(this.canonicalKey(key), {
+                value,
+                expiryTimestamp,
+            });
+        } catch (e) {
+            // Do nothing
+        }
+    }
+
+    /**
+     *
+     * @param key storage key
+     * @returns the original localstorage canonical key with prefix like "@@EXPIRABLE/key"
+     */
+    private canonicalKey(key: string): string {
+        return `${ExpirableLocalStorage.PREFIX}${key}`;
+    }
+
+    private getData(key: string): Data {
+        return JSON.parse(this.storage.getItem(key) || JSON.stringify(ExpirableLocalStorage.DEFAULT_DATA_VALUE)) as Data;
+    }
+
+    /**
+     * set Data
+     * @param key storage key
+     * @param data storage value
+     */
+    private setData(key: string, data: Data): void {
+        this.storage.setItem(key, JSON.stringify(data));
+    }
+
+    private clear(keys: string[]): void {
+        try {
+            keys.forEach(key => this.storage.removeItem(key));
+        } catch (e) {
+            // Do nothing
+        }
+    }
+
+    /**
+     * delete the expired keys
+     */
+    private prune() {
+        try {
+            const expiredKeys = Object.keys(this.storage).filter(key => {
+                if (!key.startsWith(ExpirableLocalStorage.PREFIX)) {
+                    return false;
+                }
+
+                const {expiryTimestamp} = this.getData(key);
+                return this.now() > expiryTimestamp;
+            });
+
+            this.clear(expiredKeys);
+        } catch (e) {
+            // Do nothing
+        }
+    }
+}

package/src/internal/Memo.ts

@@ -0,0 +1,28 @@
+type AnyFunctionDecorator = (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => any>) => TypedPropertyDescriptor<(...args: any[]) => any>;
+
+/**
+ * For pure functions:
+ *
+ * Memoize the last computed result, and return the same value if given the same input.
+ * Input equality is based on JSON.stringify.
+ */
+export function Memo(): AnyFunctionDecorator {
+    return (target, propertyKey, descriptor) => {
+        /**
+         * For latest decorator spec, there is only one "target" parameter, which has "descriptor" property.
+         *      https://tc39.github.io/proposal-decorators/#sec-decorator-functions-element-descriptor
+         *      https://github.com/tc39/proposal-decorators/blob/master/METAPROGRAMMING.md
+         */
+        const realDescriptor = descriptor || (target as any).descriptor;
+        const fn = realDescriptor.value!;
+        const cache: Record<string, any> = {};
+        realDescriptor.value = function (...args: any[]) {
+            const paramKey = args.length ? JSON.stringify(args) : "";
+            if (!cache[paramKey]) {
+                cache[paramKey] = fn.apply(this, args);
+            }
+            return cache[paramKey];
+        };
+        return descriptor || target;
+    };
+}

package/src/internal/NumberUtil.ts

@@ -0,0 +1,38 @@
+function rounding(value: number, algorithm: "round" | "ceil" | "floor", maxScale: number): number {
+    if (!Number.isInteger(maxScale) || maxScale < 0 || maxScale > 10) {
+        throw new Error("[web-ui] NumberUtil.rounding maxScale must be an integer in range [0, 10]");
+    }
+    /**
+     * Take "4.975" as an example.
+     * First, we split the number by the decimal point to get ["4", "975"].
+     * Then, we find the adjustmentScale ("975".length) to be 3. This means 4.975 * 10^3 is an integer.
+     * Now, we compare the maxScale with adjustmentScale.
+     * If maxScale is larger, then value * 10^maxScale is always integer which is perfect.
+     * If maxScale is smaller, then we first need to multiply the value by 10^adjustmentScale to make it an integer.
+     * Note: we need to check if adjustment is safe by checking against Number.MAX_SAFE_INTEGER.
+     * Then, we divide the number by the difference between adjustmentScale and maxScale to get the correct rounding position.
+     * For example, we have maxScale = 2. We have adjustmentScale (3) > maxScale (2).
+     * Therefore, we first get 4.975 * 10^3 = 4975. Then, we get 4975 / 10^(3 - 2) = 497.5 and we round this number.
+     * In the end, we divide this number by 10^maxScale to obtained the final answer, i.e. 498 / 10^2 = 4.98 (assume algorithm is "round").
+     */
+    const parts = Number(value).toString().split(".");
+    const adjustmentScale = parts.length < 2 ? 0 : parts[1].length;
+    const adjustmentPowerOf10 = 10 ** adjustmentScale;
+    const isAdjustmentSafe = Number(value) * adjustmentPowerOf10 <= Number.MAX_SAFE_INTEGER;
+    const powerOf10 = 10 ** maxScale;
+    if (adjustmentScale > maxScale && isAdjustmentSafe) {
+        const diffPowerOf10 = 10 ** (adjustmentScale - maxScale);
+        return Math[algorithm]((value * adjustmentPowerOf10) / diffPowerOf10) / powerOf10;
+    } else {
+        return Math[algorithm](value * powerOf10) / powerOf10;
+    }
+}
+
+function roundingToString(value: number, algorithm: "round" | "ceil" | "floor", scale: number): string {
+    return rounding(value, algorithm, scale).toFixed(scale);
+}
+
+export const NumberUtil = Object.freeze({
+    rounding,
+    roundingToString,
+});

package/src/internal/StorageHelper.ts

@@ -0,0 +1,152 @@
+/**
+ * In mobile Safari, the user may turn on "Block All Cookies".
+ * In such situation, accessing to localStorage/sessionStorage will throw error.
+ */
+
+type ClearOptions = {keys: string[] | ((key: string) => boolean)} | {exceptKeys: string[] | ((key: string) => boolean)};
+
+export class StorageHelper {
+    private static readonly trueBoolValue = "TRUE";
+    private static readonly falseBoolValue = "FALSE";
+    private globalPrefix: string | null = null;
+
+    constructor(private readonly storage: Storage) {}
+
+    setGlobalPrefix(prefix: string) {
+        this.globalPrefix = prefix;
+    }
+
+    clear(options?: ClearOptions): void {
+        try {
+            if (options) {
+                if ("keys" in options) {
+                    const {keys} = options;
+                    if (Array.isArray(keys)) {
+                        keys.forEach(key => this.storage.removeItem(key));
+                    } else {
+                        this.forEach(key => {
+                            if (keys(key)) {
+                                this.storage.removeItem(key);
+                            }
+                        });
+                    }
+                } else {
+                    const {exceptKeys} = options;
+                    this.forEach(key => {
+                        const shouldNotRemove = Array.isArray(exceptKeys) ? exceptKeys.includes(key) : exceptKeys(key);
+                        if (!shouldNotRemove) {
+                            this.storage.removeItem(key);
+                        }
+                    });
+                }
+            } else {
+                this.storage.clear();
+            }
+        } catch (e) {
+            // Do nothing
+        }
+    }
+
+    setBool(key: string, value: boolean): void {
+        this.set(key, value ? StorageHelper.trueBoolValue : StorageHelper.falseBoolValue);
+    }
+
+    setString(key: string, value: string): void {
+        this.set(key, value);
+    }
+
+    setNumber(key: string, value: number): void {
+        this.set(key, value.toString());
+    }
+
+    setObject<T extends object>(key: string, item: T): void {
+        this.set(key, JSON.stringify(item));
+    }
+
+    getBool(key: string, defaultValue: boolean): boolean {
+        const transformer = (_: string) => (_ === StorageHelper.trueBoolValue ? true : _ === StorageHelper.falseBoolValue ? false : null);
+        return this.get(key, defaultValue, transformer);
+    }
+
+    getString<T extends string = string>(key: string, defaultValue: T, validValues?: readonly T[]): T {
+        const transformer = (_: string): T | null => {
+            const typedValue = _ as T;
+            return validValues ? (validValues.includes(typedValue) ? typedValue : null) : typedValue;
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    getNumber(key: string, defaultValue: number, validator?: number[] | ((value: number) => boolean)): number {
+        const transformer = (_: string): number | null => {
+            const numberedData = Number(_);
+            if (Number.isFinite(numberedData)) {
+                if (validator === undefined) {
+                    return numberedData;
+                } else if (typeof validator === "function") {
+                    if (validator(numberedData)) {
+                        return numberedData;
+                    }
+                } else {
+                    if (validator.includes(numberedData)) {
+                        return numberedData;
+                    }
+                }
+            }
+            return null;
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    getObject<T extends object>(key: string, defaultValue: T, validator: (item: object) => boolean): T {
+        const transformer = (_: string): T | null => {
+            try {
+                const obj: object = JSON.parse(_);
+                if (validator(obj)) {
+                    return obj as T;
+                } else {
+                    return null;
+                }
+            } catch (e) {
+                return null;
+            }
+        };
+        return this.get(key, defaultValue, transformer);
+    }
+
+    getRaw(key: string): string | null {
+        try {
+            return this.storage.getItem(key);
+        } catch (e) {
+            return null;
+        }
+    }
+
+    private set(key: string, value: string): void {
+        try {
+            const prefix = this.globalPrefix ? `${this.globalPrefix}-` : "";
+            this.storage.setItem(prefix + key, value);
+        } catch (e) {
+            // Do nothing
+        }
+    }
+
+    private get<T extends string | number | boolean | object>(key: string, defaultValue: T, transformer: (value: string) => T | null) {
+        try {
+            const prefix = this.globalPrefix ? `${this.globalPrefix}-` : "";
+            const data = this.storage.getItem(prefix + key);
+            if (data !== null) {
+                const typedData = transformer(data);
+                if (typedData !== null) {
+                    return typedData;
+                }
+            }
+            return defaultValue;
+        } catch (e) {
+            return defaultValue;
+        }
+    }
+
+    private forEach(callback: (key: string, value: string) => void): void {
+        Object.keys(this.storage).forEach(key => callback(key, this.storage.getItem(key)!));
+    }
+}

package/src/internal/TextUtil.ts

@@ -0,0 +1,11 @@
+function interpolate(text: string, ...parameters: string[]): string {
+    let result = text;
+    for (let i = 0; i < parameters.length; i++) {
+        result = result.replace(`{${i + 1}}`, parameters[i]);
+    }
+    return result;
+}
+
+export const TextUtil = Object.freeze({
+    interpolate,
+});

package/src/internal/i18n/admin/en.ts

@@ -0,0 +1,18 @@
+export const en = {
+    homePageTitle: "Home Page",
+    homePageSubtitle: "Please open a page by left side menu.",
+    welcome: "Welcome to {1}",
+    logout: "Logout",
+    search: "Search",
+    reset: "Reset",
+    save: "Save",
+    expand: "Expand",
+    collapse: "Collapse",
+    goHome: "Go To Home",
+    notificationSound: "Sound Alert",
+    notFound: "The accessed page does not exist",
+    featurePermission: "Feature Permission",
+    fieldPermission: "Field Permission",
+    extraPermission: "Extra Permission",
+    language: "Language",
+};

package/src/internal/i18n/admin/index.ts

@@ -0,0 +1,13 @@
+import {en} from "./en";
+import {zh} from "./zh";
+import type {Locale} from "../../../util/LocaleUtil";
+import {LocaleUtil} from "../../../util/LocaleUtil";
+
+const i18nMap: Record<Locale, typeof en> = {
+    en,
+    zh,
+};
+
+export function i18n() {
+    return i18nMap[LocaleUtil.current()];
+}

package/src/internal/i18n/admin/zh.ts

@@ -0,0 +1,18 @@
+export const zh = {
+    homePageTitle: "管理平台首页",
+    homePageSubtitle: "请在左侧菜单选择一项打开",
+    welcome: "欢迎登录{1}",
+    logout: "登出账户",
+    search: "查询",
+    reset: "重置",
+    save: "保存修改",
+    expand: "展开",
+    collapse: "收起",
+    goHome: "返回首页",
+    notificationSound: "新通知声音",
+    notFound: "您访问的页面不存在",
+    featurePermission: "功能权限",
+    fieldPermission: "数据权限",
+    extraPermission: "其他权限",
+    language: "语言",
+};

package/src/internal/i18n/core/en.ts

@@ -0,0 +1,37 @@
+export const en = {
+    submit: "Submit",
+    all: "All",
+    yes: "Yes",
+    no: "No",
+    on: "On",
+    off: "Off",
+    delete: "Delete",
+    active: "Active",
+    inactive: "Inactive",
+    nextStep: "Next",
+    prevStep: "Previous",
+    finish: "Finish",
+    emptyData: "No Data",
+    select: "Select",
+    edit: "Edit ({1})",
+    paginationSummary: "Total {1} Records, Page {2} Out Of {3}",
+    sendAuthCode: "Send",
+    waitResendAuthCode: "Resend in {1}s",
+    confirmImageRemoval: "Are you sure to remove the image?",
+    depositPositive: "Add",
+    depositNegative: "Minus",
+    nextPage: "Next Page",
+    prevPage: "Previous Page",
+    currentPage: "Current Page",
+    noData: "No Date",
+    fold: "Fold",
+    expand: "Expand",
+    minimum: "Minimum",
+    maximum: "Maximum",
+    action: "Action",
+    sequence: "Sequence",
+    preview: "Preview",
+    upload: "Upload",
+    localImporterHint: "Click or drag {1} file to this area",
+    uploadHint: "Click Or Drag To Upload",
+};

package/src/internal/i18n/core/index.ts

@@ -0,0 +1,13 @@
+import {en} from "./en";
+import {zh} from "./zh";
+import type {Locale} from "../../../util/LocaleUtil";
+import {LocaleUtil} from "../../../util/LocaleUtil";
+
+const i18nMap: Record<Locale, typeof en> = {
+    en,
+    zh,
+};
+
+export function i18n() {
+    return i18nMap[LocaleUtil.current()];
+}

package/src/internal/i18n/core/zh.ts

@@ -0,0 +1,37 @@
+export const zh = {
+    submit: "提交",
+    all: "全部",
+    yes: "是",
+    no: "否",
+    on: "开",
+    off: "关",
+    delete: "移除",
+    active: "使用中",
+    inactive: "已停用",
+    nextStep: "下一步",
+    prevStep: "上一步",
+    finish: "完 成",
+    emptyData: "暂无数据",
+    select: "请选择",
+    edit: "修改 ({1} 个)",
+    paginationSummary: "共 {1} 条记录, 第 {2}/{3} 页",
+    sendAuthCode: "发送验证码",
+    waitResendAuthCode: "{1}秒后重发",
+    confirmImageRemoval: "确定要移除图片吗?",
+    depositPositive: "充正",
+    depositNegative: "冲负",
+    nextPage: "下一页",
+    prevPage: "上一页",
+    currentPage: "当前页",
+    noData: "暂无数据",
+    fold: "收起",
+    expand: "展开",
+    minimum: "最小值",
+    maximum: "最大值",
+    action: "操作",
+    sequence: "序列",
+    preview: "预览",
+    upload: "上传",
+    localImporterHint: "按下或拖曳 {1} 档至此",
+    uploadHint: "按下或拖曳上传",
+};

package/src/internal/i18n/util/en.ts

@@ -0,0 +1,9 @@
+export const en = {
+    defaultTitle: "System Message",
+    defaultOk: "Okay",
+    defaultConfirm: "Confirm",
+    defaultCancel: "Cancel",
+    autoClose: "Closing in {1} sec",
+    addBookmarkWithShortcut: "Please press {1} to add to bookmark",
+    addBookmarkManually: "Please add to bookmark manually",
+};

package/src/internal/i18n/util/index.ts

@@ -0,0 +1,13 @@
+import {en} from "./en";
+import {zh} from "./zh";
+import type {Locale} from "../../../util/LocaleUtil";
+import {LocaleUtil} from "../../../util/LocaleUtil";
+
+const i18nMap: Record<Locale, typeof en> = {
+    en,
+    zh,
+};
+
+export function i18n() {
+    return i18nMap[LocaleUtil.current()];
+}

package/src/internal/i18n/util/zh.ts

@@ -0,0 +1,9 @@
+export const zh = {
+    defaultTitle: "系统提示",
+    defaultOk: "知道了",
+    defaultConfirm: "确定",
+    defaultCancel: "取消",
+    autoClose: "{1} 秒后自动关闭",
+    addBookmarkWithShortcut: "请使用快捷键 {1} 添加到收藏夹",
+    addBookmarkManually: "请手动添加到收藏夹",
+};

package/src/internal/type.ts

@@ -0,0 +1,12 @@
+import type React from "react";
+
+export type SafeReactChild = React.ReactChild | boolean | null;
+export type SafeReactChildren = SafeReactChild | SafeReactChild[];
+
+export type PickOptional<T> = Pick<T, {[K in keyof T]-?: {} extends {[P in K]: T[K]} ? K : never}[keyof T]>;
+export type StringKey<T extends object> = {[P in keyof T]: T[P] extends string ? P : never}[keyof T] & string;
+
+export interface ControlledFormValue<T> {
+    value: T;
+    onChange: (value: T) => void;
+}