@mohasinac/appkit 2.2.0 → 2.3.0

package/dist/utils/number.formatter.js

@@ -1,100 +0,0 @@
-/**
- * Number Formatting Utilities
- */
-import { getDefaultCurrency, getDefaultLocale, } from "../core/baseline-resolver";
-export function formatCurrency(amount, currency, locale) {
-    const resolvedCurrency = currency ?? getDefaultCurrency();
-    const resolvedLocale = locale ?? getDefaultLocale();
-    return new Intl.NumberFormat(resolvedLocale, {
-        style: "currency",
-        currency: resolvedCurrency,
-    }).format(amount);
-}
-export function formatNumber(num, locale, options) {
-    const resolvedLocale = locale ?? getDefaultLocale();
-    return new Intl.NumberFormat(resolvedLocale, {
-        minimumFractionDigits: options?.decimals,
-        maximumFractionDigits: options?.decimals,
-    }).format(num);
-}
-export function formatPercentage(num, decimals = 0) {
-    return `${(num * 100).toFixed(decimals)}%`;
-}
-export function formatFileSize(bytes) {
-    if (bytes === 0)
-        return "0 Bytes";
-    const k = 1024;
-    const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
-}
-export function formatCompactNumber(num) {
-    if (num < 1000)
-        return num.toString();
-    if (num < 1000000)
-        return `${(num / 1000).toFixed(1)}K`;
-    if (num < 1000000000)
-        return `${(num / 1000000).toFixed(1)}M`;
-    return `${(num / 1000000000).toFixed(1)}B`;
-}
-export function formatDecimal(num, decimals = 2) {
-    return num.toFixed(decimals);
-}
-export function formatOrdinal(num) {
-    const suffixes = ["th", "st", "nd", "rd"];
-    const value = num % 100;
-    return num + (suffixes[(value - 20) % 10] || suffixes[value] || suffixes[0]);
-}
-export function parseFormattedNumber(str) {
-    const isNegative = /^-/.test(str) || str.includes("-");
-    let cleaned = str.replace(/[^\d,.]/g, "");
-    if (cleaned === "" || cleaned === "0")
-        return 0;
-    const lastCommaIndex = cleaned.lastIndexOf(",");
-    const lastDotIndex = cleaned.lastIndexOf(".");
-    const commaCount = (cleaned.match(/,/g) || []).length;
-    const dotCount = (cleaned.match(/\./g) || []).length;
-    let decimalSeparator = ".";
-    let thousandsSeparator = ",";
-    if (lastCommaIndex > -1 && lastDotIndex > -1) {
-        if (lastCommaIndex > lastDotIndex) {
-            decimalSeparator = ",";
-            thousandsSeparator = ".";
-        }
-    }
-    else if (lastDotIndex > -1 && lastCommaIndex === -1) {
-        const afterDot = cleaned.substring(lastDotIndex + 1);
-        if (dotCount > 1) {
-            cleaned = cleaned.replace(/\./g, "");
-        }
-        else if (afterDot.length > 3) {
-            cleaned = cleaned.replace(/\./g, "");
-        }
-        decimalSeparator = ".";
-        thousandsSeparator = "";
-    }
-    else if (lastCommaIndex > -1 && lastDotIndex === -1) {
-        const afterComma = cleaned.substring(lastCommaIndex + 1);
-        if (commaCount > 1) {
-            cleaned = cleaned.replace(/,/g, "");
-            decimalSeparator = ".";
-            thousandsSeparator = "";
-        }
-        else if (afterComma.length > 3) {
-            cleaned = cleaned.replace(/,/g, "");
-            decimalSeparator = ".";
-            thousandsSeparator = "";
-        }
-        else {
-            decimalSeparator = ",";
-            thousandsSeparator = "";
-        }
-    }
-    let result = cleaned;
-    if (thousandsSeparator) {
-        result = result.replace(new RegExp("\\" + thousandsSeparator, "g"), "");
-    }
-    result = result.replace(decimalSeparator, ".");
-    const num = parseFloat(result);
-    return isNegative ? -Math.abs(num) : num;
-}

package/dist/utils/object.helper.d.ts

@@ -1,16 +0,0 @@
-/**
- * Object Data Helpers
- *
- * Generic helpers for object data operations — no external dependencies.
- */
-export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
-export declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
-export declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-export declare function isEmptyObject(obj: Record<string, unknown>): boolean;
-export declare function deepClone<T>(obj: T): T;
-export declare function isEqual(obj1: unknown, obj2: unknown): boolean;
-export declare function cleanObject<T extends Record<string, unknown>>(obj: T, options?: {
-    removeEmpty?: boolean;
-    removeNull?: boolean;
-    removeUndefined?: boolean;
-}): Partial<T>;

package/dist/utils/object.helper.js

@@ -1,82 +0,0 @@
-/**
- * Object Data Helpers
- *
- * Generic helpers for object data operations — no external dependencies.
- */
-export function deepMerge(target, source) {
-    const output = { ...target };
-    Object.keys(source).forEach((key) => {
-        const sourceValue = source[key];
-        const targetValue = target[key];
-        if (sourceValue &&
-            typeof sourceValue === "object" &&
-            !Array.isArray(sourceValue) &&
-            targetValue &&
-            typeof targetValue === "object" &&
-            !Array.isArray(targetValue)) {
-            output[key] = deepMerge(targetValue, sourceValue);
-        }
-        else {
-            output[key] = sourceValue;
-        }
-    });
-    return output;
-}
-export function pick(obj, keys) {
-    const result = {};
-    keys.forEach((key) => {
-        if (key in obj)
-            result[key] = obj[key];
-    });
-    return result;
-}
-export function omit(obj, keys) {
-    const result = { ...obj };
-    keys.forEach((key) => {
-        delete result[key];
-    });
-    return result;
-}
-export function isEmptyObject(obj) {
-    return Object.keys(obj).length === 0;
-}
-export function deepClone(obj) {
-    if (obj === null || typeof obj !== "object")
-        return obj;
-    if (Array.isArray(obj))
-        return obj.map((item) => deepClone(item));
-    const cloned = {};
-    const objectRecord = obj;
-    Object.keys(objectRecord).forEach((key) => {
-        cloned[key] = deepClone(objectRecord[key]);
-    });
-    return cloned;
-}
-export function isEqual(obj1, obj2) {
-    if (obj1 === obj2)
-        return true;
-    if (typeof obj1 !== "object" ||
-        typeof obj2 !== "object" ||
-        obj1 === null ||
-        obj2 === null) {
-        return false;
-    }
-    const first = obj1;
-    const second = obj2;
-    const keys1 = Object.keys(first);
-    const keys2 = Object.keys(second);
-    if (keys1.length !== keys2.length)
-        return false;
-    return keys1.every((key) => isEqual(first[key], second[key]));
-}
-export function cleanObject(obj, options = {}) {
-    const { removeEmpty = true, removeNull = true, removeUndefined = true, } = options;
-    return Object.entries(obj).reduce((acc, [key, value]) => {
-        const shouldRemove = (removeUndefined && value === undefined) ||
-            (removeNull && value === null) ||
-            (removeEmpty && value === "");
-        if (!shouldRemove)
-            acc[key] = value;
-        return acc;
-    }, {});
-}

package/dist/utils/pagination.helper.d.ts

@@ -1,23 +0,0 @@
-/**
- * Pagination Helper
- *
- * Generic helpers for pagination metadata calculations.
- */
-export interface PaginationOptions {
-    page: number;
-    perPage: number;
-    total: number;
-}
-export interface PaginationResult {
-    currentPage: number;
-    perPage: number;
-    total: number;
-    totalPages: number;
-    hasNextPage: boolean;
-    hasPrevPage: boolean;
-    nextPage: number | null;
-    prevPage: number | null;
-    startIndex: number;
-    endIndex: number;
-}
-export declare function calculatePagination(options: PaginationOptions): PaginationResult;

package/dist/utils/pagination.helper.js

@@ -1,24 +0,0 @@
-/**
- * Pagination Helper
- *
- * Generic helpers for pagination metadata calculations.
- */
-export function calculatePagination(options) {
-    const { page, perPage, total } = options;
-    const totalPages = Math.ceil(total / perPage);
-    const currentPage = Math.max(1, Math.min(page, totalPages));
-    const startIndex = (currentPage - 1) * perPage;
-    const endIndex = Math.min(startIndex + perPage, total);
-    return {
-        currentPage,
-        perPage,
-        total,
-        totalPages,
-        hasNextPage: currentPage < totalPages,
-        hasPrevPage: currentPage > 1,
-        nextPage: currentPage < totalPages ? currentPage + 1 : null,
-        prevPage: currentPage > 1 ? currentPage - 1 : null,
-        startIndex,
-        endIndex,
-    };
-}

package/dist/utils/schema-ui.d.ts

@@ -1,83 +0,0 @@
-/**
- * deriveFormFields — @mohasinac/appkit/utils
- *
- * Schema → UI pipeline: automatically derive `ExtraFormField[]`-compatible
- * field configurations from a Zod object schema shape.
- *
- * This bridges the "Schema → UI → Action" pipeline gap: when a consumer
- * extends an appkit Zod schema with `.extend({ hsn: z.string() })`, they can
- * call `deriveFormFields(extendedSchema)` to get ready-to-use field configs
- * instead of manually authoring them.
- *
- * ## Design
- * - Works with any Zod `ZodObject` (or `ZodEffects` wrapping one)
- * - Infers `type`, `label`, `required`, `options` from the Zod type and metadata
- * - Compatible with `ExtraFormField` from `@mohasinac/appkit/contracts`
- * - Zero runtime dependency on React — returns plain config objects
- *
- * @example
- * ```ts
- * import { productCreateSchema } from "@mohasinac/appkit/features/products";
- * import { deriveFormFields } from "@mohasinac/appkit/utils";
- *
- * const extended = productCreateSchema.extend({
- *   hsn: z.string().describe("HSN Code"),
- *   origin: z.enum(["domestic", "imported"]).describe("Product Origin"),
- * });
- *
- * const fields = deriveFormFields(extended);
- * // → [{ key: "hsn", label: "HSN Code", inputType: "text", required: true }, ...]
- *
- * // Use directly as ExtraFormField render configs:
- * <ProductForm extraFields={fields.map(fieldToExtraFormField)} />
- * ```
- */
-export type DerivedFieldType = "text" | "textarea" | "number" | "boolean" | "select" | "multiselect" | "date" | "unknown";
-export interface DerivedFieldOption {
-    value: string;
-    label: string;
-}
-/**
- * A single derived field configuration, inferred from a Zod schema shape.
- */
-export interface DerivedField {
-    /** The field key (matches the Zod schema property name). */
-    key: string;
-    /** Human-readable label, derived from the Zod `.describe()` annotation or camelCase key. */
-    label: string;
-    /** The inferred input type. */
-    inputType: DerivedFieldType;
-    /** Whether the field is required (non-optional, non-nullable Zod type). */
-    required: boolean;
-    /** For `select` and `multiselect` — the enum options. */
-    options?: DerivedFieldOption[];
-    /** The original Zod type descriptor string (for debugging). */
-    zodTypeName: string;
-}
-/**
- * Options for `deriveFormFields`.
- */
-export interface DeriveFormFieldsOptions {
-    /**
-     * Keys to omit from the derived field list.
-     * Use to skip system-managed fields like `id`, `createdAt`, `updatedAt`.
-     * Default: `["id", "createdAt", "updatedAt", "deletedAt"]`
-     */
-    omit?: string[];
-    /**
-     * Keys to include. If provided, only these keys are returned (in order).
-     * Overrides `omit`.
-     */
-    include?: string[];
-}
-/**
- * Derive `DerivedField[]` from a Zod object schema.
- *
- * Accepts any `ZodObject`, `ZodEffects(ZodObject)`, or any object with a
- * `.shape` property (duck-typed — no hard Zod import).
- *
- * @param schema   The Zod schema to introspect.
- * @param options  Optional config: `omit`, `include`.
- * @returns        Array of `DerivedField` descriptors, one per schema property.
- */
-export declare function deriveFormFields(schema: unknown, options?: DeriveFormFieldsOptions): DerivedField[];

package/dist/utils/schema-ui.js

@@ -1,185 +0,0 @@
-/**
- * deriveFormFields — @mohasinac/appkit/utils
- *
- * Schema → UI pipeline: automatically derive `ExtraFormField[]`-compatible
- * field configurations from a Zod object schema shape.
- *
- * This bridges the "Schema → UI → Action" pipeline gap: when a consumer
- * extends an appkit Zod schema with `.extend({ hsn: z.string() })`, they can
- * call `deriveFormFields(extendedSchema)` to get ready-to-use field configs
- * instead of manually authoring them.
- *
- * ## Design
- * - Works with any Zod `ZodObject` (or `ZodEffects` wrapping one)
- * - Infers `type`, `label`, `required`, `options` from the Zod type and metadata
- * - Compatible with `ExtraFormField` from `@mohasinac/appkit/contracts`
- * - Zero runtime dependency on React — returns plain config objects
- *
- * @example
- * ```ts
- * import { productCreateSchema } from "@mohasinac/appkit/features/products";
- * import { deriveFormFields } from "@mohasinac/appkit/utils";
- *
- * const extended = productCreateSchema.extend({
- *   hsn: z.string().describe("HSN Code"),
- *   origin: z.enum(["domestic", "imported"]).describe("Product Origin"),
- * });
- *
- * const fields = deriveFormFields(extended);
- * // → [{ key: "hsn", label: "HSN Code", inputType: "text", required: true }, ...]
- *
- * // Use directly as ExtraFormField render configs:
- * <ProductForm extraFields={fields.map(fieldToExtraFormField)} />
- * ```
- */
-function unwrapZodType(zodType) {
-    const typeName = zodType._def?.typeName ?? "";
-    // Unwrap ZodOptional, ZodNullable, ZodDefault, ZodEffects
-    if (typeName === "ZodOptional" ||
-        typeName === "ZodNullable" ||
-        typeName === "ZodDefault") {
-        const inner = zodType._def?.innerType;
-        if (inner)
-            return unwrapZodType(inner);
-    }
-    if (typeName === "ZodEffects") {
-        const inner = zodType._def?.schema;
-        if (inner)
-            return unwrapZodType(inner);
-    }
-    return zodType;
-}
-function getZodTypeName(zodType) {
-    return unwrapZodType(zodType)._def?.typeName ?? "unknown";
-}
-function isRequired(zodType) {
-    const typeName = zodType._def?.typeName ?? "";
-    return (typeName !== "ZodOptional" &&
-        typeName !== "ZodNullable" &&
-        typeName !== "ZodDefault");
-}
-function getEnumOptions(unwrapped) {
-    const typeName = unwrapped._def?.typeName ?? "";
-    if (typeName === "ZodEnum") {
-        const values = unwrapped._def?.values;
-        if (Array.isArray(values)) {
-            return values.map((v) => ({
-                value: v,
-                label: v.charAt(0).toUpperCase() + v.slice(1).replace(/_/g, " "),
-            }));
-        }
-        if (values && typeof values === "object") {
-            return Object.entries(values).map(([, v]) => ({
-                value: v,
-                label: v.charAt(0).toUpperCase() +
-                    v.slice(1).replace(/_/g, " "),
-            }));
-        }
-    }
-    if (typeName === "ZodNativeEnum") {
-        const values = unwrapped._def?.values;
-        if (values && typeof values === "object" && !Array.isArray(values)) {
-            return Object.entries(values)
-                .filter(([k]) => isNaN(Number(k))) // skip reverse numeric mappings
-                .map(([, v]) => ({
-                value: v,
-                label: v.charAt(0).toUpperCase() +
-                    v.slice(1).replace(/_/g, " "),
-            }));
-        }
-    }
-    return undefined;
-}
-function inferInputType(zodType) {
-    const unwrapped = unwrapZodType(zodType);
-    const typeName = getZodTypeName(zodType);
-    const options = getEnumOptions(unwrapped);
-    if (options) {
-        return { inputType: "select", options };
-    }
-    switch (typeName) {
-        case "ZodString": {
-            const checks = unwrapped._def?.checks;
-            if (Array.isArray(checks)) {
-                const hasMax = checks.some((c) => c.kind === "max" && typeof c.value === "number" && c.value > 200);
-                if (hasMax)
-                    return { inputType: "textarea" };
-            }
-            return { inputType: "text" };
-        }
-        case "ZodNumber":
-        case "ZodBigInt":
-            return { inputType: "number" };
-        case "ZodBoolean":
-            return { inputType: "boolean" };
-        case "ZodDate":
-            return { inputType: "date" };
-        case "ZodArray": {
-            const itemType = unwrapped._def?.type ?? unwrapped._def?.items;
-            if (itemType) {
-                const itemOptions = getEnumOptions(unwrapZodType(itemType));
-                if (itemOptions)
-                    return { inputType: "multiselect", options: itemOptions };
-            }
-            return { inputType: "text" };
-        }
-        default:
-            return { inputType: "unknown" };
-    }
-}
-function keyToLabel(key) {
-    // camelCase → "Title Case With Spaces"
-    return key
-        .replace(/([A-Z])/g, " $1")
-        .replace(/^./, (s) => s.toUpperCase())
-        .replace(/_/g, " ")
-        .trim();
-}
-const DEFAULT_OMIT = ["id", "createdAt", "updatedAt", "deletedAt"];
-/**
- * Derive `DerivedField[]` from a Zod object schema.
- *
- * Accepts any `ZodObject`, `ZodEffects(ZodObject)`, or any object with a
- * `.shape` property (duck-typed — no hard Zod import).
- *
- * @param schema   The Zod schema to introspect.
- * @param options  Optional config: `omit`, `include`.
- * @returns        Array of `DerivedField` descriptors, one per schema property.
- */
-export function deriveFormFields(schema, options = {}) {
-    const zodLike = schema;
-    // Unwrap ZodEffects to reach the ZodObject
-    const unwrapped = unwrapZodType(zodLike);
-    const shape = unwrapped.shape;
-    if (!shape || typeof shape !== "object") {
-        return [];
-    }
-    const omitSet = new Set(options.omit ?? DEFAULT_OMIT);
-    const includeSet = options.include ? new Set(options.include) : undefined;
-    const allKeys = Object.keys(shape);
-    const filteredKeys = allKeys.filter((key) => {
-        if (includeSet)
-            return includeSet.has(key);
-        return !omitSet.has(key);
-    });
-    const ordered = includeSet
-        ? [...(options.include ?? [])].filter((k) => filteredKeys.includes(k))
-        : filteredKeys;
-    return ordered.map((key) => {
-        const fieldType = shape[key];
-        const unwrappedField = unwrapZodType(fieldType);
-        const description = fieldType.description ??
-            fieldType._def?.description ??
-            unwrappedField.description ??
-            unwrappedField._def?.description;
-        const { inputType, options: fieldOptions } = inferInputType(fieldType);
-        return {
-            key,
-            label: description ? String(description) : keyToLabel(key),
-            inputType,
-            required: isRequired(fieldType),
-            options: fieldOptions,
-            zodTypeName: getZodTypeName(fieldType),
-        };
-    });
-}

package/dist/utils/sorting.helper.d.ts

@@ -1,7 +0,0 @@
-/**
- * Sorting Helper
- *
- * Generic helpers for sorting operations.
- */
-export type SortOrder = "asc" | "desc";
-export declare function sort<T>(array: T[], key: keyof T, order?: SortOrder): T[];

package/dist/utils/sorting.helper.js

@@ -1,16 +0,0 @@
-/**
- * Sorting Helper
- *
- * Generic helpers for sorting operations.
- */
-export function sort(array, key, order = "asc") {
-    return [...array].sort((a, b) => {
-        const aVal = a[key];
-        const bVal = b[key];
-        if (aVal < bVal)
-            return order === "asc" ? -1 : 1;
-        if (aVal > bVal)
-            return order === "asc" ? 1 : -1;
-        return 0;
-    });
-}

package/dist/utils/string.formatter.d.ts

@@ -1,19 +0,0 @@
-/**
- * String Formatting and Manipulation Utilities
- */
-export declare function capitalize(str: string): string;
-export declare function capitalizeWords(str: string): string;
-export declare function truncate(str: string, maxLength: number, suffix?: string): string;
-export declare function truncateWords(str: string, wordCount: number, suffix?: string): string;
-export declare function stripHtml(html: string): string;
-/** Escapes HTML special characters to prevent XSS attacks. */
-export declare function escapeHtml(str: string): string;
-export declare function slugify(str: string): string;
-export declare function maskString(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string;
-export declare function randomString(length?: number): string;
-export declare function isEmptyString(str: string | null | undefined): boolean;
-/**
- * Converts a ProseMirror/TipTap JSON document string to HTML.
- * Falls back to returning the value unchanged if it is not a ProseMirror doc.
- */
-export declare function proseMirrorToHtml(value: string): string;