@atomazing-org/design-system 1.0.5 → 1.0.6

package/README.MD

@@ -1,34 +1,206 @@
-# Atomazing Design System
+# 📚 Table of Contents
 
-[![MIT License](https://img.shields.io/npm/l/npm-package-example.svg?style=flat-square)](http://opensource.org/licenses/MIT)
+1. [Introduction](#1-introduction)
+2. [Installation](#2-installation)
+3. [Usage](#3-usage)  
+   3.1 [Theme Provider Setup](#31-theme-provider-setup)  
+   3.2 [Typography Variants](#32-typography-variants)  
+   3.3 [Global Styles](#33-global-styles)  
+   3.4 [Component Overrides](#34-component-overrides)
+4. [Utilities](#4-utilities)  
+   4.1 [Color Utilities](#41-color-utilities)  
+   4.2 [System Info](#42-system-info)
+5. [Animations](#5-animations)
+6. [Theming](#6-theming)  
+   6.1 [Theme Creation](#61-theme-creation)  
+   6.2 [Dark Mode Strategy](#62-dark-mode-strategy)
+7. [Typography Configuration](#7-typography-configuration)
+8. [Contributing](#8-contributing)
+9. [License](#9-license)
 
-The `@atomazing-org/design-system` provides a set of useful utils, mui style extensions and components to build your application the way Atomazing does.
+## 1. Introduction
 
-## Build-on
+**@atomazing-org/design-system** is a reusable, opinionated design system built on top of [Material UI (MUI)](https://mui.com/) and [Emotion](https://emotion.sh/).  
+It offers a consistent foundation for building modern web interfaces with minimal configuration.
 
-`"@mui/material": "^5.15.21"`
+This package provides:
 
-`"@mui/icons-material": "^5.15.11"`
+- 🌈 Customizable MUI theme generator
+- ✍️ Extended typography variants
+- 🎨 Global styles (with dark/light mode support)
+- 🧩 Component style overrides
+- 🛠 Utility functions (e.g., color contrast, system info)
+- 🎞 Smooth keyframe animations
 
-`"@emotion/css": "^11.11.2"`
+The design system is ideal for teams working across multiple front-end applications who want to unify styles, reduce duplication, and ship faster with consistent UI patterns.
 
-## Installation
+## 2. Installation
 
-Just install package from npm
+To install the design system in your project, use your preferred package manager:
 
+```bash
+# Using npm
+npm install @atomazing-org/design-system
 ```
-npm i @atomazing-org/design-system
+
+```bash
+# Using yarn
+yarn add @atomazing-org/design-system
+```
+
+```bash
+# Using pnpm
+pnpm add @atomazing-org/design-system
+```
+
+
+## 3. Peer Dependencies & Requirements
+
+The `@atomazing-org/design-system` package relies on several peer dependencies to integrate properly with your application stack.
+
+Make sure the following libraries are installed in your project:
+
+| Package              | Version          | Required For                        |
+|----------------------|------------------|-------------------------------------|
+| `@mui/material`      | `^7.2.0`         | Core MUI theming and components     |
+| `@mui/icons-material`| `^7.2.0`         | Icon support                        |
+| `@emotion/react`     | `^11.0.0`        | Emotion styling engine (required)   |
+| `@emotion/styled`    | `^11.0.0`        | Styled components with Emotion      |
+| `@emotion/css`       | `^11.13.5`       | (Optional) Raw className utility    |
+
+### TypeScript Support
+
+This package is fully written in TypeScript and ships with `.d.ts` type declarations.
+Ensure your project uses TypeScript 4.5+ for best compatibility.
+
+> ✅ **Tip:** If you encounter missing types (e.g., for `@emotion/react`), install them manually:
+```bash
+npm install -D @types/react
+```
+
+## 4. Features Overview
+
+This package provides a modular and extendable foundation for your design system, broken into the following areas:
+
+### 🎨 Theme Generator (`createCustomTheme`)
+- Dynamically generate MUI themes using custom primary and secondary colors.
+- Supports light, dark, system, and auto modes.
+- Automatically adapts based on background contrast.
+
+### 🧩 Component Overrides (`commonComponentProps`)
+- Global style customizations for common MUI components (e.g. `Button`, `Tooltip`, `Dialog`, `Slider`).
+- Shared defaults to ensure consistent spacing, border-radius, shadows, and blur effects.
+
+### ✍️ Typography Variants (`typographyVariants`)
+- Dozens of additional font sizes and weights beyond MUI defaults.
+- Uses names like `text_md_regular`, `display_lg_bold` for clarity and structure.
+- Easily configurable in your MUI theme's `typography` field.
+
+### 🖥 Global Styles (`GlobalStyles`)
+- Applies global CSS resets and base styles (scrollbars, font, highlight colors).
+- Reacts to theme mode (`light` or `dark`) to dynamically adjust UI contrast.
+- Uses Emotion’s `<Global />` component under the hood.
+
+### 🎞 Animations (`keyframes`)
+- Predefined keyframes for fade, slide, scale, and pulse effects.
+- Includes customizable utilities like `pulseAnimation(color)` and `progressPulse(color)`.
+
+### 🛠 Utilities
+- `getFontColor`: Calculates readable font color from a background hex.
+- `isDarkMode`: Detects appropriate mode based on system or color contrast.
+- `systemInfo`: Returns the user's OS and browser in a reliable format.
+
+---
+
+These modules are built to be tree-shakable and can be imported individually.
+
+## 5. Usage Examples
+
+This section shows how to integrate the design system in your React application.
+
+### 5.1. Wrapping with ThemeProvider
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+import {
+  createCustomTheme,
+  GlobalStyles,
+} from '@atomazing-org/design-system';
+
+import { ThemeProvider, CssBaseline } from '@mui/material';
+
+const theme = createCustomTheme('#4461F2', '#F9F9FC', 'light');
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <ThemeProvider theme={theme}>
+    <CssBaseline />
+    <GlobalStyles />
+    <App />
+  </ThemeProvider>,
+);
 ```
 
-## Package structure
+## 6. Customization
+
+The design system is built to be flexible and extendable. You can override or extend the default behavior in several ways.
+
+### 6.1. Customizing the Theme
+
+You can generate your own theme using `createCustomTheme`:
 
+```ts
+import { createCustomTheme } from '@atomazing-org/design-system';
+
+const theme = createCustomTheme(
+  '#0088cc', // primary color
+  '#f0f4f8', // background (secondary) color
+  'light',   // palette mode
+);
 ```
-├── src
-│   ├── components  // React components
-│   ├── styles      // Mui style extensions and themeing tools
-│   └──utils        // Useful util functions
-├── index.ts
-├── tsconfig.json
-├── package.json
-└── README.md
+
+## 7. Tree-Shaking & Importing
+
+The `@atomazing-org/design-system` package is optimized for modern bundlers and supports tree-shaking out of the box.
+
+To minimize bundle size:
+
+### 7.1. Use Named Imports
+
+Instead of importing everything at once, prefer named imports:
+
+```ts
+// ✅ Recommended (tree-shakable)
+import { fadeIn, getFontColor } from '@atomazing-org/design-system';
+
+// 🚫 Not recommended (bundles everything)
+import * as DesignSystem from '@atomazing-org/design-system';
+```
+
+## 8. Contribution Guide
+
+We welcome contributions to the design system! Whether it's improving styles, fixing bugs, or adding utilities — every improvement helps.
+
+### 8.1. Getting Started
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/atomazing/design-system.git
+cd design-system
+npm install
 ```
+
+## 9. License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+You are free to use, modify, distribute, and sublicense the design system in your projects, whether personal or commercial.
+
+---
+
+© PonomarevBPM + MarkSinD, 2025  
+Maintained under the Atomazing Org initiative.
+

package/dist/index.d.mts

@@ -0,0 +1,297 @@
+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 } 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';
+import { TypographyVariantsOptions } from '@mui/material/styles/createTypography';
+
+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>, {}>;
+
+/**
+ * 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"];
+
+/**
+ * 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";
+/**
+ * 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;
+}
+
+/**
+ * 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";
+
+/**
+ * Generates a custom MUI theme using a primary color, background color, and color mode.
+ *
+ * @param primaryColor - The main color used for primary palette.
+ * @param backgroundColor - Background color (used as secondary). Defaults to dark blue.
+ * @param mode - MUI palette mode ('light' | 'dark'). Defaults to 'dark'.
+ * @returns A MUI Theme object.
+ */
+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;
+
+/**
+ * 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;
+}>;
+
+/**
+ * Default MUI Typography variant-to-element mapping.
+ * Custom variants are mapped to HTML tags like <p>, <h1>, etc.
+ */
+declare const typographyProps: Theme["components"];
+/**
+ * Custom typography variants.
+ * Defines font-weight, size, line-height and optionally fallback font.
+ */
+declare const typographyVariants: TypographyVariantsOptions;
+
+/**
+ * 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;
+
+export { type AppSettings, ColorPalette, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, PathName, type SystemTheme, commonComponentProps, createCustomTheme, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, typographyProps, typographyVariants, useResponsiveDisplay };