@gofreego/tsutils 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,555 @@
+import React, { ReactNode, CSSProperties } from 'react';
+import { IconButtonProps } from '@mui/material';
+
+/**
+ * Menu item configuration
+ */
+interface MenuItem {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Optional icon element */
+    icon?: ReactNode;
+    /** Route path (for router mode) */
+    path?: string;
+    /** Component to render (for non-router mode) */
+    component?: ReactNode;
+    /** Optional submenu items */
+    children?: MenuItem[];
+}
+interface SidebarLayoutProps {
+    /** Array of menu items */
+    menuItems: MenuItem[];
+    /** Width of the sidebar */
+    sidebarWidth?: string | number;
+    /** Additional CSS class for container */
+    className?: string;
+    /** Default selected menu item ID (for non-router mode) */
+    defaultSelected?: string;
+    /** Callback when menu changes */
+    onMenuChange?: (id: string) => void;
+    /** Custom styles for container */
+    style?: CSSProperties;
+    /** Custom styles for sidebar */
+    sidebarStyle?: CSSProperties;
+    /** Custom styles for body */
+    bodyStyle?: CSSProperties;
+    /** Default expanded submenu IDs */
+    defaultExpanded?: string[];
+    /** If true, wraps SidebarLayout in BrowserRouter and enables router-based navigation */
+    isRouter?: boolean;
+}
+/**
+ * SidebarLayout Component
+ *
+ * A flexible sidebar-body layout component built with Material UI that supports
+ * both router-based and state-based navigation with nested submenu support.
+ *
+ * **Uses Material UI Components:**
+ * - Drawer (permanent variant)
+ * - List, ListItem, ListItemButton
+ * - ListItemIcon, ListItemText
+ * - Collapse (for submenus)
+ * - Box for layout
+ *
+ * **Features:**
+ * - Nested submenu support with expand/collapse
+ * - Material UI icons (ExpandMore/ExpandLess)
+ * - Recursive rendering for deep nesting
+ * - Automatic indentation based on depth
+ *
+ * **Router Mode** (when react-router-dom is available):
+ * - Uses NavLink for navigation
+ * - Renders child routes via Outlet
+ * - Supports URL-based navigation
+ * - Browser back/forward works
+ *
+ * **State Mode** (fallback):
+ * - Uses internal state
+ * - Renders components from menuItems
+ * - Simple navigation without routing
+ *
+ * @example
+ * // With nested submenus
+ * <SidebarLayout
+ *   menuItems={[
+ *     {
+ *       id: 'products',
+ *       label: 'Products',
+ *       icon: <ShoppingCartIcon />,
+ *       children: [
+ *         { id: 'all-products', label: 'All Products', path: '/products/all' },
+ *         { id: 'categories', label: 'Categories', path: '/products/categories' }
+ *       ]
+ *     },
+ *     { id: 'dashboard', label: 'Dashboard', path: '/dashboard', icon: <DashboardIcon /> }
+ *   ]}
+ *   defaultExpanded={['products']}
+ * />
+ *
+ * @example
+ * // With React Router
+ * <Routes>
+ *   <Route path="/" element={
+ *     <SidebarLayout menuItems={[
+ *       { id: 'dashboard', label: 'Dashboard', path: '/dashboard', icon: <DashboardIcon /> },
+ *       { id: 'settings', label: 'Settings', path: '/settings', icon: <SettingsIcon /> }
+ *     ]} />
+ *   }>
+ *     <Route path="dashboard" element={<Dashboard />} />
+ *     <Route path="settings" element={<Settings />} />
+ *   </Route>
+ * </Routes>
+ *
+ * @example
+ * // Without React Router (State-based)
+ * <SidebarLayout
+ *   menuItems={[
+ *     { id: 'dashboard', label: 'Dashboard', component: <Dashboard /> },
+ *     { id: 'settings', label: 'Settings', component: <Settings /> }
+ *   ]}
+ *   defaultSelected="dashboard"
+ * />
+ */
+declare const SidebarLayout: React.FC<SidebarLayoutProps>;
+
+/**
+ * Theme mode options
+ * - 'light': Always use light theme
+ * - 'dark': Always use dark theme
+ * - 'system': Follow system preference (prefers-color-scheme)
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+/**
+ * Resolved theme mode (actual theme being displayed)
+ */
+type ResolvedThemeMode = 'light' | 'dark';
+/**
+ * Theme interface with comprehensive design tokens
+ */
+interface Theme {
+    colors: {
+        primary: string;
+        primaryHover: string;
+        primaryActive: string;
+        secondary: string;
+        secondaryHover: string;
+        secondaryActive: string;
+        background: string;
+        backgroundSecondary: string;
+        backgroundTertiary: string;
+        surface: string;
+        surfaceHover: string;
+        text: string;
+        textSecondary: string;
+        textTertiary: string;
+        textDisabled: string;
+        error: string;
+        errorHover: string;
+        errorBackground: string;
+        success: string;
+        successHover: string;
+        successBackground: string;
+        warning: string;
+        warningHover: string;
+        warningBackground: string;
+        info: string;
+        infoHover: string;
+        infoBackground: string;
+        border: string;
+        borderHover: string;
+        borderFocus: string;
+        divider: string;
+        overlay: string;
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+    };
+    borderRadius: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        full: string;
+    };
+    fontSize: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+        '4xl': string;
+    };
+    fontWeight: {
+        light: string;
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        tight: string;
+        normal: string;
+        relaxed: string;
+    };
+    elevation: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    transition: {
+        fast: string;
+        normal: string;
+        slow: string;
+    };
+    zIndex: {
+        dropdown: number;
+        sticky: number;
+        fixed: number;
+        modalBackdrop: number;
+        modal: number;
+        popover: number;
+        tooltip: number;
+    };
+}
+/**
+ * Theme context value
+ */
+interface ThemeContextValue {
+    /** Current theme object */
+    theme: Theme;
+    /** Selected theme mode (can be 'system') */
+    themeMode: ThemeMode;
+    /** Resolved theme mode (actual theme being displayed: 'light' or 'dark') */
+    resolvedThemeMode: ResolvedThemeMode;
+    /** Set custom theme object */
+    setTheme: (theme: Theme) => void;
+    /** Set theme mode */
+    setThemeMode: (mode: ThemeMode) => void;
+    /** Toggle between light and dark (skips system) */
+    toggleTheme: () => void;
+}
+
+interface ThemeProviderProps {
+    children: ReactNode;
+    /** Custom theme object (overrides default light/dark themes) */
+    initialTheme?: Theme;
+    /** Initial theme mode */
+    initialMode?: ThemeMode;
+    /** localStorage key for persisting theme preference */
+    storageKey?: string;
+    /** Enable CSS variables injection */
+    enableCssVariables?: boolean;
+}
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+
+declare const useTheme: () => ThemeContextValue;
+
+interface ThemeToggleProps extends Omit<IconButtonProps, 'onClick'> {
+    /**
+     * Tooltip text for light mode
+     * @default "Switch to dark mode"
+     */
+    lightModeTooltip?: string;
+    /**
+     * Tooltip text for dark mode
+     * @default "Switch to light mode"
+     */
+    darkModeTooltip?: string;
+    /**
+     * Whether to show tooltip
+     * @default true
+     */
+    showTooltip?: boolean;
+}
+/**
+ * A round button component for toggling between light and dark themes
+ * Note: Toggling skips 'system' mode and switches directly between light and dark
+ */
+declare const ThemeToggle: React.FC<ThemeToggleProps>;
+
+/**
+ * Light theme configuration
+ * Colors are WCAG AA compliant with minimum contrast ratio of 4.5:1 for normal text
+ * and 3:1 for large text
+ */
+declare const lightTheme: Theme;
+
+/**
+ * Dark theme configuration
+ * Colors are WCAG AA compliant with minimum contrast ratio of 4.5:1 for normal text
+ * and 3:1 for large text on dark backgrounds
+ */
+declare const darkTheme: Theme;
+
+/**
+ * Design Tokens - Theme-agnostic values
+ * These tokens serve as the foundation for light and dark themes
+ * Following Material Design 3 principles
+ */
+/**
+ * Spacing scale based on 4px grid system
+ */
+declare const spacing: {
+    readonly xs: "0.25rem";
+    readonly sm: "0.5rem";
+    readonly md: "1rem";
+    readonly lg: "1.5rem";
+    readonly xl: "2rem";
+    readonly '2xl': "3rem";
+    readonly '3xl': "4rem";
+};
+/**
+ * Border radius tokens
+ */
+declare const borderRadius: {
+    readonly none: "0";
+    readonly sm: "0.25rem";
+    readonly md: "0.375rem";
+    readonly lg: "0.5rem";
+    readonly xl: "0.75rem";
+    readonly '2xl': "1rem";
+    readonly full: "9999px";
+};
+/**
+ * Typography scale
+ */
+declare const fontSize: {
+    readonly xs: "0.75rem";
+    readonly sm: "0.875rem";
+    readonly md: "1rem";
+    readonly lg: "1.125rem";
+    readonly xl: "1.25rem";
+    readonly '2xl': "1.5rem";
+    readonly '3xl': "1.875rem";
+    readonly '4xl': "2.25rem";
+};
+/**
+ * Font weights
+ */
+declare const fontWeight: {
+    readonly light: "300";
+    readonly normal: "400";
+    readonly medium: "500";
+    readonly semibold: "600";
+    readonly bold: "700";
+};
+/**
+ * Line heights
+ */
+declare const lineHeight: {
+    readonly tight: "1.25";
+    readonly normal: "1.5";
+    readonly relaxed: "1.75";
+};
+/**
+ * Elevation (box shadows) for depth perception
+ */
+declare const elevation: {
+    readonly none: "none";
+    readonly sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)";
+    readonly md: "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)";
+    readonly lg: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)";
+    readonly xl: "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)";
+};
+/**
+ * Transition durations
+ */
+declare const transition: {
+    readonly fast: "150ms";
+    readonly normal: "250ms";
+    readonly slow: "350ms";
+};
+/**
+ * Z-index scale for layering
+ */
+declare const zIndex: {
+    readonly dropdown: 1000;
+    readonly sticky: 1020;
+    readonly fixed: 1030;
+    readonly modalBackdrop: 1040;
+    readonly modal: 1050;
+    readonly popover: 1060;
+    readonly tooltip: 1070;
+};
+
+declare const tokens_borderRadius: typeof borderRadius;
+declare const tokens_elevation: typeof elevation;
+declare const tokens_fontSize: typeof fontSize;
+declare const tokens_fontWeight: typeof fontWeight;
+declare const tokens_lineHeight: typeof lineHeight;
+declare const tokens_spacing: typeof spacing;
+declare const tokens_transition: typeof transition;
+declare const tokens_zIndex: typeof zIndex;
+declare namespace tokens {
+  export { tokens_borderRadius as borderRadius, tokens_elevation as elevation, tokens_fontSize as fontSize, tokens_fontWeight as fontWeight, tokens_lineHeight as lineHeight, tokens_spacing as spacing, tokens_transition as transition, tokens_zIndex as zIndex };
+}
+
+interface HttpClientConfig {
+    baseURL?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+interface RequestConfig extends Omit<RequestInit, 'body'> {
+    params?: Record<string, string | number | boolean>;
+    data?: any;
+    timeout?: number;
+}
+interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+}
+
+declare class HttpClient {
+    private baseURL;
+    private timeout;
+    private defaultHeaders;
+    constructor(config?: HttpClientConfig);
+    private buildURL;
+    private request;
+    get<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
+    put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
+    patch<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
+    delete<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+}
+
+/**
+ * Merges class names together
+ * Useful for conditional className composition
+ */
+declare function cn(...classes: (string | undefined | null | false)[]): string;
+
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+
+/**
+ * Creates a throttled function that only invokes func at most once per every wait milliseconds
+ */
+declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+
+/**
+ * Formats a date to a readable string
+ */
+declare function formatDate(date: Date | string | number, options?: Intl.DateTimeFormatOptions): string;
+
+/**
+ * LocalStorage utility for safely storing and retrieving data
+ */
+declare class LocalStorage {
+    /**
+     * Get an item from localStorage
+     * @param key - The key to retrieve
+     * @returns The value or null if not found or error occurs
+     */
+    static getItem<T = string>(key: string): T | null;
+    /**
+     * Set an item in localStorage
+     * @param key - The key to store
+     * @param value - The value to store
+     * @returns true if successful, false otherwise
+     */
+    static setItem<T>(key: string, value: T): boolean;
+    /**
+     * Remove an item from localStorage
+     * @param key - The key to remove
+     * @returns true if successful, false otherwise
+     */
+    static removeItem(key: string): boolean;
+    /**
+     * Clear all items from localStorage
+     * @returns true if successful, false otherwise
+     */
+    static clear(): boolean;
+    /**
+     * Check if a key exists in localStorage
+     * @param key - The key to check
+     * @returns true if key exists, false otherwise
+     */
+    static hasItem(key: string): boolean;
+    /**
+     * Get all keys from localStorage
+     * @returns Array of keys
+     */
+    static keys(): string[];
+}
+
+/**
+ * Context State Interface
+ */
+interface AuthContextType {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+}
+interface AuthProviderProps {
+    /** Name of the cookie containing the JWT token. Defaults to "authorization" */
+    cookieName?: string;
+    /** URL to redirect the user to if authentication fails */
+    redirectUrl: string;
+    /** Components to render if deeply authenticated */
+    children: ReactNode;
+    /** Custom fallback logic to fire upon failed auth (overrides redirectUrl behavior) */
+    onAuthFail?: () => void;
+    /** Custom callback fired strictly on successful auth */
+    onAuthSuccess?: () => void;
+    /** Optional loading element while checking cookies asynchronously */
+    loadingElement?: ReactNode;
+}
+/**
+ * AuthProvider verifies a JWT embedded in document.cookie.
+ * Checks for existence, decodes the signature, and evaluates the `exp` claim.
+ * Redirects heavily dependent or kicks custom callbacks if failed.
+ */
+declare const AuthProvider: React.FC<AuthProviderProps>;
+/**
+ * React Hook for easily accessing the authenticated JWT context
+ */
+declare const useAuth: () => AuthContextType;
+
+/**
+ * A utility class to manage user permissions using the browser's localStorage.
+ * Employs an internal memory cache to prevent repeated synchronous parsing.
+ */
+declare class PermissionManager {
+    private static cachedPermissions;
+    /**
+     * Saves an array of permission strings to local storage.
+     * @param permissions Array of permission strings.
+     */
+    static setPermissions(permissions: string[]): void;
+    /**
+     * Retrieves the currently stored permissions from local storage or memory cache.
+     * @returns Array of permission strings, or an empty array if none exist.
+     */
+    static getPermissions(): string[];
+    /**
+     * Clears all stored permissions from memory and local storage.
+     */
+    static clearPermissions(): void;
+    /**
+     * Checks whether the given permission string exists in the currently stored permissions.
+     * @param permission The permission string to check for.
+     * @returns True if the permission exists, false otherwise.
+     */
+    static hasPermission(permission: string): boolean;
+}
+
+export { type AuthContextType, AuthProvider, type AuthProviderProps, HttpClient, type HttpClientConfig, type HttpResponse, LocalStorage, type MenuItem, PermissionManager, type RequestConfig, type ResolvedThemeMode, SidebarLayout, type SidebarLayoutProps, type Theme, type ThemeContextValue, type ThemeMode, ThemeProvider, ThemeToggle, borderRadius, cn, darkTheme, debounce, elevation, fontSize, fontWeight, formatDate, lightTheme, lineHeight, spacing, throttle, tokens, transition, useAuth, useTheme, zIndex };