# blqthien/react-number-format architecture

> Architecture diagram of the GitHub repository blqthien/react-number-format, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blqthien/react-number-format
- Repository: https://github.com/blqthien/react-number-format

## Overview

This project is a reusable React library named “react-number-format” that provides sophisticated input formatting (both numeric and custom-pattern formats) with a dedicated caret engine. It is designed to allow users to enter text that conforms to specific numeric or string patterns and to display a formatted version of that value. Given that it is a library rather than a full application, its architecture mainly revolves around well-isolated formatting modules that are integrated with React components.

##### Main Components
- Core Library (src):
– Components: The entry point (src/index.ts) and individual formatting implementations such as NumericFormat (src/numeric_format.tsx), PatternFormat (src/pattern_format.tsx), and the supporting number_format_base.tsx.
– Utilities: Helper functions and type definitions (src/utils.tsx, src/types.ts) provide the underlying formatting logic.
- Custom Formatter Extensions:
– Located in the custom_formatters directory (e.g., custom_formatters/card_expiry.js), these modules enable users to plug in custom formatting rules.
- Testing Infrastructure:
– The test directory contains unit tests (e.g., test/library, test/custom_formatters) ensuring each module behaves as expected.
– Includes configuration files (karma.conf.js) and tests written in jasmine/karma.
- Documentation & Examples:
– The documentation folder (especially documentation/v5) includes a full Docusaurus-based guide on usage, customization, migration from v4, and more.
– An example directory provides a minimal demonstration (example/index.html and example/src/index.js) of how to use the library.
- Build and Tooling:
– Build configurations (rollup.config.js, webpack.config.js, tsconfig.json) and other configuration files (.babelrc, .eslintrc, .prettierrc, etc.) indicate the project’s bundling, linting, and type-checking tooling.
– The package.json lists dependencies and build scripts.

##### Relationships and Data Flow
- User Interaction → React Components:
– In an application, the developer uses the exported components (NumericFormat, PatternFormat). These components are illustrated as the “entry point” into the library.
- Component Internals:
– Once a component is used, it taps into the base formatting logic (number_format_base.tsx) for managing input, alongside utility functions (from src/utils.tsx) that handle tasks like caret positioning, number manipulation, and formatting.
– If custom formatting is needed, the module will delegate to custom formatters (custom_formatters).
- Testing and Documentation:
– The documentation (both v4 and v5 directories) and examples serve as an interface for developers, highlighting usage patterns and integration examples.

##### Architectural Patterns and Design Principles
- Modularity: Each formatting type (numeric and pattern) is developed as an isolated module that can be imported independently.
- Separation of Concerns: Clear division between the UI components (React components rendering the formatted input), underlying formatting logic, and custom extensions.
- Extensibility: The custom_formatters folder shows that the design anticipates user extension.
- Testing & Continuous Integration: The presence of dedicated test folders and continuous integration workflows (in .github/workflows) indicates a reliable development pipeline.

##### Relevant Technologies
- React: The core library is built as React components.
- Webpack, Rollup, and Babel: For module bundling and transpilation.
- TypeScript: The src directory uses .ts/.tsx files to add types and improved reliability.
- Testing: Jasmine/Karma are used for running unit tests, as shown in the test directory.
- Documentation: Docusaurus is used for generating versioned documentation (see documentation/v5/docusaurus.config.js).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Interaction
    U("User Input/Developer Integration"):::external

    %% Core Library Subgraph
    subgraph "Core Library"
        CL1("Entry Point"):::core
        CL2("NumericFormat (API)"):::core
        CL3("PatternFormat (API)"):::core
        CL4("Base Formatting Engine"):::core
        CL5("Utilities"):::core
        CL6("Type Definitions"):::core
    end

    %% Custom Formatter Extensions Subgraph
    subgraph "Custom Formatter Extensions"
        CF1("Custom Formatter Module(s)"):::custom
    end

    %% Build and Tooling Subgraph
    subgraph "Build and Tooling"
        BT1("Build Configurations"):::build
        BT2("Package Dependencies & Scripts"):::build
    end

    %% Testing Infrastructure Subgraph
    subgraph "Testing Infrastructure"
        TI1("Unit Tests"):::testing
    end

    %% Documentation & Examples Subgraph
    subgraph "Documentation & Examples"
        DE1("Documentation"):::docs
        DE2("Example Usage"):::docs
    end

    %% Connections: User Interaction to Core Library Entry Point
    U -->|"uses"| CL1

    %% Core Library: Entry Point exporting API components
    CL1 -->|"exports"| CL2
    CL1 -->|"exports"| CL3

    %% API Components invoking Formatting Engine
    CL2 -->|"formatsUsing"| CL4
    CL3 -->|"formatsUsing"| CL4

    %% Formatting Engine utilizing Utilities and Types
    CL4 -->|"utilizes"| CL5
    CL4 -->|"utilizes"| CL6

    %% API Components optionally delegating to Custom Formatter Extensions
    CL2 -->|"canDelegate"| CF1
    CL3 -->|"canDelegate"| CF1

    %% Build and Tooling integration with Core Library
    CL1 -->|"bundledBy"| BT1
    CL1 -->|"referencedIn"| BT2
    BT1 -->|"buildIntegration"| CL1

    %% Testing link
    CL2 -->|"testedBy"| TI1
    CL3 -->|"testedBy"| TI1
    CL4 -->|"testedBy"| TI1
    CL5 -->|"testedBy"| TI1

    %% Documentation & Examples connections
    CL1 -->|"documentedIn"| DE1
    CL2 -->|"documentedIn"| DE1
    CL3 -->|"documentedIn"| DE1
    DE2 -->|"demonstratesUsageOf"| CL1

    %% Click Events
    click CL1 "https://github.com/blqthien/react-number-format/blob/master/src/index.ts"
    click CL2 "https://github.com/blqthien/react-number-format/blob/master/src/numeric_format.tsx"
    click CL3 "https://github.com/blqthien/react-number-format/blob/master/src/pattern_format.tsx"
    click CL4 "https://github.com/blqthien/react-number-format/blob/master/src/number_format_base.tsx"
    click CL5 "https://github.com/blqthien/react-number-format/blob/master/src/utils.tsx"
    click CL6 "https://github.com/blqthien/react-number-format/blob/master/src/types.ts"
    click CF1 "https://github.com/blqthien/react-number-format/tree/master/custom_formatters"
    click TI1 "https://github.com/blqthien/react-number-format/tree/master/test"
    click DE1 "https://github.com/blqthien/react-number-format/tree/master/documentation"
    click DE2 "https://github.com/blqthien/react-number-format/tree/master/example"
    click BT1 "https://github.com/blqthien/react-number-format/blob/master/rollup.config.js"
    click BT2 "https://github.com/blqthien/react-number-format/blob/master/package.json"

    %% Styles
    classDef core fill:#B3CDE0,stroke:#000,stroke-width:2px,color:#000;
    classDef custom fill:#CDEBA7,stroke:#000,stroke-width:2px,color:#000;
    classDef testing fill:#F8B500,stroke:#000,stroke-width:2px,color:#000;
    classDef docs fill:#D3BFBF,stroke:#000,stroke-width:2px,color:#000;
    classDef build fill:#F9AFAE,stroke:#000,stroke-width:2px,color:#000;
    classDef external fill:#FFDFBA,stroke:#000,stroke-width:2px,color:#000;
```
