@atomazing-org/design-system/dist/index.d.ts

A library providing a set of useful utils, MUI style extensions, and components to build your application.

import * as _emotion_styled from '@emotion/styled';
import * as _emotion_react from '@emotion/react';
import * as React$1 from 'react';
import React__default, { ErrorInfo, FC, PropsWithChildren } from 'react';
import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
import * as _mui_material from '@mui/material';
import { Theme, PaletteMode } from '@mui/material';
import * as react_jsx_runtime from 'react/jsx-runtime';

declare const DialogBtn: _emotion_styled.StyledComponent<_mui_material.ButtonOwnProps & Omit<_mui_material.ButtonBaseOwnProps, "classes"> & _mui_material_OverridableComponent.CommonProps & Omit<React$1.DetailedHTMLProps<React$1.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "style" | "className" | "classes" | "action" | "centerRipple" | "children" | "disabled" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "focusVisibleClassName" | "LinkComponent" | "onFocusVisible" | "sx" | "tabIndex" | "TouchRippleProps" | "touchRippleRef" | "href" | "color" | "disableElevation" | "disableFocusRipple" | "endIcon" | "fullWidth" | "loading" | "loadingIndicator" | "loadingPosition" | "size" | "startIcon" | "variant"> & {
    theme?: _emotion_react.Theme;
}, {}, {}>;

interface ErrorBoundaryProps {
    children: React__default.ReactNode;
}
interface ErrorBoundaryState {
    hasError: boolean;
    error?: Error;
}
/**
 * ErrorBoundary component that catches and displays errors.
 */
declare class ErrorBoundary extends React__default.Component<ErrorBoundaryProps, ErrorBoundaryState> {
    constructor(props: ErrorBoundaryProps);
    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
    render(): string | number | bigint | boolean | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
}

declare const Loading: () => react_jsx_runtime.JSX.Element;

declare const PathName: _emotion_styled.StyledComponent<{
    theme?: _emotion_react.Theme;
    as?: React.ElementType;
}, React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLElement>, HTMLElement>, {}>;

/**
 * Available options for dark mode configuration.
 * - `system`: Follows the operating system preference.
 * - `auto`: Uses contrast-based detection (e.g., based on background color).
 * - `light`: Forces light mode.
 * - `dark`: Forces dark mode.
 */
type DarkModeOptions = "system" | "auto" | "light" | "dark";
interface OptionItem {
    label: string;
    value: DarkModeOptions;
    icon: any;
}
/**
 * Represents user-specific theme preferences stored in the application.
 */
interface AppSettings {
    /**
     * The selected theme name. `"system"` indicates the app should follow system preference.
     * Other values are custom theme names defined by the application.
     */
    theme: "system" | (string & {});
    /**
     * Controls how dark mode is applied in the app.
     */
    darkMode: DarkModeOptions;
}
interface ThemeContextProps {
    theme: string;
    darkMode: DarkModeOptions;
    setTheme: (theme: string) => void;
    setDarkMode: (mode: DarkModeOptions) => void;
}

/**
 * Represents the theme mode as reported by the operating system or browser.
 * - `light`: Light mode
 * - `dark`: Dark mode
 * - `unknown`: Theme mode could not be determined
 */
type SystemTheme = "light" | "dark" | "unknown";

interface CustomTypographyVariants {
    text_xl_regular: {
        font: string;
    };
    text_lg_regular: {
        font: string;
    };
    text_md_regular: {
        font: string;
    };
    text_sm_regular: {
        font: string;
    };
    text_xs_regular: {
        font: string;
    };
    text_2xs_regular: {
        font: string;
    };
    text_xl_bold: {
        font: string;
    };
    text_lg_bold: {
        font: string;
    };
    text_md_bold: {
        font: string;
    };
    text_sm_bold: {
        font: string;
    };
    text_xs_bold: {
        font: string;
    };
    text_2xs_bold: {
        font: string;
    };
    text_xl_semibold: {
        font: string;
    };
    text_lg_semibold: {
        font: string;
    };
    text_md_semibold: {
        font: string;
    };
    text_sm_semibold: {
        font: string;
    };
    text_xs_semibold: {
        font: string;
    };
    text_2xs_semibold: {
        font: string;
    };
    text_xl_thin: {
        font: string;
    };
    text_lg_thin: {
        font: string;
    };
    text_md_thin: {
        font: string;
    };
    text_sm_thin: {
        font: string;
    };
    text_xs_thin: {
        font: string;
    };
    text_2xs_thin: {
        font: string;
    };
    header_2xl_regular: {
        font: string;
    };
    header_xl_regular: {
        font: string;
    };
    header_lg_regular: {
        font: string;
    };
    header_md_regular: {
        font: string;
    };
    header_sm_regular: {
        font: string;
    };
    header_xs_regular: {
        font: string;
    };
    header_2xl_bold: {
        font: string;
    };
    header_xl_bold: {
        font: string;
    };
    header_lg_bold: {
        font: string;
    };
    header_md_bold: {
        font: string;
    };
    header_sm_bold: {
        font: string;
    };
    header_xs_bold: {
        font: string;
    };
}
declare module "@mui/material/styles" {
    interface TypographyVariants extends CustomTypographyVariants {
    }
    interface TypographyVariantsOptions extends Partial<CustomTypographyVariants> {
    }
}
declare module "@mui/material/Typography" {
    interface TypographyPropsVariantOverrides extends Record<keyof CustomTypographyVariants, true> {
    }
}

declare const useThemeSettings: () => ThemeContextProps;

declare const ThemeProviderWrapper: FC<PropsWithChildren>;

/**
 * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
 *
 * @param value - The string to check.
 * @returns `true` if the string is a valid hex color; otherwise, `false`.
 */
declare const isHexColor: (value: string) => boolean;
/**
 * Determines the ideal font color (white or black) for contrast against a given background color.
 *
 * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
 *
 * @param backgroundColor - A valid hex color (e.g., "#ffffff").
 * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
 */
declare const getFontColor: (backgroundColor: string) => string;
/**
 * Determines whether the ideal font color for a background is light (i.e., white).
 *
 * @param color - The background color in hex.
 * @returns `true` if white text is recommended; otherwise, `false`.
 */
declare const isFontLight: (color: string) => boolean;

/**
 * Common component style overrides and default props shared across the design system.
 * This object should be spread into the `components` field of the MUI theme.
 */
declare const commonComponentProps: Theme["components"];

declare const createCustomTheme: (primaryColor: string, backgroundColor?: string, mode?: PaletteMode) => Theme;
/**
 * A predefined list of named themes based on the `themeConfig` definition.
 */
declare const themes: {
    name: string;
    MuiTheme: Theme;
}[];
/**
 * Determines whether dark mode should be enabled based on user settings and system conditions.
 *
 * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
 * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
 * @param backgroundColor - The background color to assess contrast in 'auto' mode.
 * @returns True if dark mode should be used.
 */
declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme, backgroundColor: string) => boolean;

declare const darkModeOptions: OptionItem[];

/**
 * Injects global styles into the document using Emotion.
 * These styles include font setup, base HTML styles, custom scrollbars,
 * selection styling, and some accessibility tweaks.
 *
 * Uses the MUI theme to dynamically adjust colors for light/dark mode.
 */
declare const GlobalStyles: FC;

/**
 * Fade in from the left with slight movement on the X-axis.
 */
declare const fadeInLeft: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Simple fade in animation (opacity only).
 */
declare const fadeIn: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Slide in from the left side of the screen.
 */
declare const slideIn: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Slide in from the bottom of the screen.
 */
declare const slideInBottom: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Scale from 0 to full size.
 */
declare const scale: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Creates a pulsating animation using scale and box-shadow.
 * Simulates a glowing effect.
 *
 * @param clr - The base color for the shadow in hex format.
 * @param shadowBlur - The maximum spread of the shadow during the pulse (default: 12).
 * @returns Emotion keyframes animation.
 */
declare const pulseAnimation: (clr: string, shadowBlur?: number) => {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Creates a glowing pulse animation using drop-shadow.
 * Used in progress or highlight elements.
 *
 * @param clr - The glow color in hex.
 * @returns Emotion keyframes animation.
 */
declare const progressPulse: (clr: string) => {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * A bounce-scale animation used during logout transition.
 */
declare const logoutAnimation: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;
/**
 * Subtle bounce animation used for install app prompts.
 */
declare const installAppAnimation: {
    name: string;
    styles: string;
    anim: 1;
    toString: () => string;
} & string;

declare const ColorPalette: {
    readonly fontDark: "#101727";
    readonly fontLight: "#f0f0f0";
    readonly darkMode: "#383838";
    readonly lightMode: "#ffffff";
    readonly purple: "#b624ff";
    readonly red: "#ff3131";
    readonly orange: "#ff9318";
    readonly orangeDark: "#ff9500";
};
declare const themeConfig: Record<string, {
    primaryColor: string;
    secondaryColor?: string;
}>;

/**
 * Returns a greeting based on the current time.
 * @returns {string} The appropriate greeting.
 */
declare const displayGreeting: () => string;

/**
 * Function to extract year, month, and day from a Date object
 */
declare const getDayIdentifier: (date: Date) => string;

/**
 * A list of supported operating systems.
 */
type OperatingSystem = "Windows" | "macOS" | "Linux" | "iOS" | "Android" | "Unknown";
/**
 * A list of supported browsers.
 */
type Browser = "Chrome" | "Firefox" | "Safari" | "Edge" | "Unknown";
/**
 * Basic information about the user's system (OS and browser).
 */
declare const systemInfo: {
    os: OperatingSystem;
    browser: Browser;
};

/**
 * Converts a given date to a human-readable relative time string.
 *
 * @param {Date} date - The date to be converted.
 * @param lang
 * @returns {string} A string representing the relative time using `Intl` format (e.g., "2 days ago").
 */
declare const timeAgo: (date: Date, lang?: string) => string;
declare const timeAgoFromStart: (date: Date, lang?: string) => string;

/**
 * A custom React hook to determine if the current device is a smaller device
 * based on the screen width.
 * @param [breakpoint=768] - The breakpoint in pixels at which a device is considered "smaller".
 * @returns {boolean} - A boolean value indicating whether the current device is a smaller device.
 */
declare const useResponsiveDisplay: (breakpoint?: number) => boolean;

/**
 * A React hook to detect the system theme preference.
 * @returns The current system theme ('light', 'dark', or 'unknown').
 */
declare const useSystemTheme: () => SystemTheme;

export { type AppSettings, ColorPalette, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };