@tap-payments/os-micro-frontend-shared 0.1.491 → 0.1.492-test.2

package/docs/03-architecture.md

@@ -0,0 +1,438 @@
+# Architecture Guide
+
+System architecture, design decisions, and build system for the component library.
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview) - Package structure and exports
+2. [Folder Structure](#folder--module-structure) - Source code organization
+3. [Module Connections](#module-connections) - Import relationships
+4. [Design Decisions](#design-decisions--constraints) - Technical constraints and rationale
+5. [Build System](#build-system) - Compilation and output
+6. [Path Aliases](#path-aliases) - Import paths in source
+7. [Export Strategy](#export-strategy) - Consumer import patterns
+8. [Tech Stack Summary](#tech-stack-summary) - Dependencies overview
+
+## Architecture Overview
+
+### Package Exports
+
+| Export Path | Contents | Purpose |
+|-------------|----------|---------|
+| `/` | All exports | Main entry point with everything |
+| `/components` | All UI components | Component library exports |
+| `/components/*` | Individual components | Granular component imports |
+| `/hooks` | Custom React hooks | Hook utilities |
+| `/utils` | Utility functions | Helper functions |
+| `/types` | TypeScript definitions | Type interfaces |
+| `/constants` | App constants | Configuration values |
+| `/theme` | MUI theme config | Theme factory and customization |
+
+### Dependency Flow
+
+**1. Consumption (who imports what)**
+
+Consumer apps import from the package entry; the package re-exports from its internal modules. Types and constants are consumed by the library itself and by consumers who need type imports.
+
+```mermaid
+flowchart TB
+  subgraph External["Micro frontends"]
+    Consumer["Consumer Apps"]
+  end
+
+  subgraph PackageEntry["Package entry"]
+    Entry["Main Entry"]
+  end
+
+  subgraph PackageExports["Package export paths"]
+    E1["/components"]
+    E2["/hooks"]
+    E3["/utils"]
+    E4["/types"]
+    E5["/constants"]
+    E6["/theme"]
+  end
+
+  Consumer -->|import from @tap-payments/...| Entry
+  Entry --> E1
+  Entry --> E2
+  Entry --> E3
+  Entry --> E4
+  Entry --> E5
+  Entry --> E6
+
+  Consumer -.->|provided by consumer| Peer["React, MUI, Emotion, RHF, etc."]
+
+```
+
+**2. Internal dependencies (what depends on what inside the package)**
+
+Components sit at the top of the internal dependency graph; they may use hooks, utils, types, constants, and theme. Hooks and utils depend only on types (and utils on constants). Theme depends on MUI. Types and constants have no internal package dependencies.
+
+```mermaid
+flowchart TB
+  subgraph Internal["Package internal (src/)"]
+    Components[Components]
+    Hooks[Hooks]
+    Utils[Utils]
+    Theme[Theme]
+    Types[Types]
+    Constants[Constants]
+  end
+
+  subgraph ExternalDeps["External (peer deps)"]
+    MUI[MUI createTheme]
+  end
+
+  Components --> Hooks
+  Components --> Utils
+  Components --> Types
+  Components --> Constants
+  Components --> Theme
+
+  Hooks --> Types
+  Hooks --> Utils
+
+  Utils --> Types
+  Utils --> Constants
+
+  Theme --> MUI
+```
+
+**3. Layer summary**
+
+| Layer | Depends on | Description |
+|-------|------------|-------------|
+| **Consumer apps** | Package entry | Import from `@tap-payments/os-micro-frontend-shared` or subpaths (`/components`, `/hooks`, etc.). |
+| **Package entry** | All module indices | Re-exports from `components`, `hooks`, `utils`, `types`, `constants`, `theme`. |
+| **Components** | hooks, utils, types, constants, theme | UI components use hooks (e.g. useToast), utils (formatting, validation), types (props), constants (config), theme (styled components). |
+| **Hooks** | types, utils | Custom hooks use type definitions and utility functions. |
+| **Utils** | types, constants | Pure helpers with type safety and config/constants. |
+| **Theme** | MUI createTheme | Theme factory (palette, typography, components, shadows). |
+| **Types** | — | No internal deps; consumed by components, hooks, utils. |
+| **Constants** | — | No internal deps; consumed by components, utils. |
+| **All modules** | Peer dependencies | React, MUI, Emotion, etc. are provided by the consumer at runtime. |
+
+---
+
+## Folder / Module Structure
+
+```
+src/
+├── index.ts              # Main entry point - re-exports all modules
+│
+├── components/           # 100+ UI components (1000+ files)
+│   ├── [ComponentName]/  # Each component in its own folder
+│   │   ├── index.ts      # Public exports
+│   │   ├── Component.tsx # Main component
+│   │   ├── style.ts      # Styled components (Emotion)
+│   │   └── types.ts      # Component-specific types
+│   └── index.ts          # Aggregates all component exports
+│
+├── hooks/                # 18 custom React hooks
+│   ├── index.ts          # Aggregates all hook exports
+│   ├── useWindowDimensions.ts
+│   ├── useThemeMode.ts
+│   ├── useToast.ts
+│   └── ...
+│
+├── utils/                # 47 utility modules
+│   ├── index.ts          # Aggregates all util exports
+│   ├── date.ts           # Date formatting utilities
+│   ├── currency.ts       # Currency utilities
+│   ├── api.ts            # API helpers
+│   └── ...
+│
+├── types/                # 37 TypeScript type definition files
+│   ├── index.ts          # Aggregates all type exports
+│   ├── theme.ts          # Theme types
+│   ├── api.ts            # API types
+│   └── ...
+│
+├── constants/            # 41 constant definition files
+│   ├── index.ts          # Aggregates all constant exports
+│   ├── apps.ts           # App constants
+│   ├── currency.ts       # Currency constants
+│   └── ...
+│
+├── theme/                # MUI theme configuration
+│   ├── index.ts          # Theme exports
+│   ├── theme.ts          # appTheme() factory function
+│   ├── palette.ts        # Light/dark color palettes
+│   ├── typography.ts     # Font configurations
+│   ├── components.ts     # MUI component overrides
+│   └── shadows.ts        # Shadow definitions
+│
+└── demo/                 # Development examples (not exported)
+    ├── Table/            # Table demo components
+    ├── Forms/            # Form demo components
+    └── ...
+```
+
+---
+
+## Module Connections
+
+| Module | Imports From | Purpose |
+|--------|--------------|---------|
+| components | hooks | useActionMenu, useToast, useWindowDimensions, etc. |
+| components | utils | Formatting, validation, data manipulation |
+| components | types | Prop interfaces and type definitions |
+| components | constants | Config values, enums, static data |
+| components | theme | Styled components, palette, typography |
+| hooks | types, utils | Type definitions and utility functions |
+| utils | types, constants | Type safety and configuration values |
+
+### Theme System Flow
+
+```mermaid
+flowchart TD
+  A[appTheme(mode, direction)] --> B{mode}
+  B -->|light| C[lightPalette]
+  B -->|dark| D[darkPalette]
+  A --> E{direction}
+  E -->|ltr / rtl| F[typography & layout]
+  C --> G[MUI createTheme]
+  D --> G
+  F --> G
+  G --> H[Consumer: MUIThemeProvider]
+```
+
+---
+
+## Design Decisions & Constraints
+
+### Why ESM-Only Build?
+
+- Modern bundlers (Vite, Webpack 5+) prefer ESM
+- Tree-shaking works best with ESM
+- Peer dependencies avoid duplication
+- `preserveModules: true` maintains import paths
+
+### Why Peer Dependencies?
+
+Package expects consumer to provide:
+
+- react ^18, react-dom ^18
+- @mui/material ^5, @emotion/react ^11, @emotion/styled ^11
+- framer-motion ^10, react-hook-form ^7
+- Others: see `package.json` peerDependencies
+
+**Reason:** Prevents version conflicts and bundle bloat.
+
+### Why No Tests in Package?
+
+- Components tested in consuming applications
+- Visual testing preferred (Storybook in consumers)
+- Types provide compile-time safety
+- Lint-staged ensures code quality
+
+### Why Path Aliases?
+
+**Benefits:** Cleaner imports in source, easier refactoring, consistent paths, IDE autocomplete.
+
+**Implementation:** `tsconfig.json` defines aliases; `tsc-alias` resolves them at build time. Consumers use package exports, not aliases.
+
+---
+
+## Build System
+
+### Build Output Structure
+
+```
+build/
+├── index.js              # Main entry
+├── index.d.ts            # Type definitions
+├── components/
+│   ├── index.js
+│   ├── index.d.ts
+│   ├── [Component]/
+│   │   ├── index.js
+│   │   └── index.d.ts
+├── hooks/
+├── utils/
+├── types/
+├── constants/
+└── theme/
+```
+
+### Build Process
+
+```mermaid
+flowchart TD
+  A[yarn ts:build] --> B[rm -rf build]
+  B --> C[tsc -p tsconfig.npm.json]
+  C --> D[Compile .ts → .js]
+  C --> E[Generate .d.ts files]
+  C --> F[Output to build/]
+  A --> G[tsc-alias -p tsconfig.npm.json]
+  G --> H[Resolve path aliases]
+  H --> I["@components → ./components"]
+```
+
+### Build Configuration
+
+**vite.config.ts** (for dev server):
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| lib.entry | src/index.ts | Entry point |
+| formats | ['es'] | ESM only |
+| preserveModules | true | Keep folder structure |
+| external | react, react-dom, react/jsx-runtime | Peer deps |
+| outDir | build | Output directory |
+
+**tsconfig.npm.json** (for production build):
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| target | ES2015 | Browser compatibility |
+| module | ES2015 | ESM |
+| declaration | true | Generate .d.ts |
+| declarationMap | true | Source maps for types |
+| outDir | build | Output directory |
+| paths | {...} | Path aliases |
+
+---
+
+## Path Aliases
+
+### Internal Path Aliases (Source Code)
+
+Use these in imports within the library source only:
+
+| Alias | Resolves To |
+|-------|-------------|
+| `@types` | src/types/ |
+| `@utils` | src/utils/ |
+| `@constants` | src/constants/ |
+| `@theme` | src/theme/ |
+| `@components` | src/components/ |
+| `@components/*` | src/components/* |
+| `@hooks` | src/hooks/ |
+
+**Configuration** (tsconfig.json):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@constants": ["src/constants/index.ts"],
+      "@utils": ["src/utils/index.ts"],
+      "@types": ["src/types/index.ts"],
+      "@theme": ["src/theme/index.ts"],
+      "@components": ["src/components/index.ts"],
+      "@components/*": ["src/components/*"],
+      "@hooks": ["src/hooks/index.ts"]
+    }
+  }
+}
+```
+
+Consumers use package exports, not path aliases:
+
+```typescript
+// ✓ Correct (consumer code)
+import { Button } from '@tap-payments/os-micro-frontend-shared'
+
+// ✗ Wrong (internal only)
+import { Button } from '@components'
+```
+
+---
+
+## Export Strategy
+
+### Package.json Exports Map
+
+Consumers can import from multiple entry points:
+
+```typescript
+// Main entry (everything)
+import { Button, useToast, formatCurrency } from '@tap-payments/os-micro-frontend-shared'
+
+// Specific modules (tree-shaking friendly)
+import { Button } from '@tap-payments/os-micro-frontend-shared/components'
+import { useToast } from '@tap-payments/os-micro-frontend-shared/hooks'
+import { formatCurrency } from '@tap-payments/os-micro-frontend-shared/utils'
+import type { Column } from '@tap-payments/os-micro-frontend-shared/types'
+import { CURRENCY_SYMBOLS } from '@tap-payments/os-micro-frontend-shared/constants'
+import { appTheme } from '@tap-payments/os-micro-frontend-shared/theme'
+
+// Specific component (granular imports)
+import { Button } from '@tap-payments/os-micro-frontend-shared/components/Button'
+```
+
+**package.json**:
+
+```json
+{
+  "exports": {
+    ".": "./build/index.js",
+    "./components": "./build/components/index.js",
+    "./components/*": "./build/components/*/index.js",
+    "./hooks": "./build/hooks/index.js",
+    "./utils": "./build/utils/index.js",
+    "./types": "./build/types/index.js",
+    "./constants": "./build/constants/index.js",
+    "./theme": "./build/theme/index.js"
+  }
+}
+```
+
+---
+
+## Tech Stack Summary
+
+### Core Dependencies (Peer)
+
+```mermaid
+flowchart LR
+  subgraph Runtime
+    R1[React 18]
+    R2[TypeScript 5]
+    R3[ES2015]
+  end
+  subgraph UI
+    U1[MUI 5]
+    U2[Emotion]
+    U3[Framer Motion 10]
+  end
+  subgraph Forms
+    F1[React Hook Form 7]
+    F2[Yup]
+  end
+  subgraph Data
+    D1[Axios]
+    D2[dayjs]
+    D3[i18next]
+  end
+  subgraph Virtualization
+    V1[react-window]
+    V2[react-window-infinite-loader]
+  end
+```
+
+| Category | Key Dependencies |
+|----------|-------------------|
+| Runtime | React 18, TypeScript 5.0, ES2015 target |
+| UI | MUI 5, Emotion, Framer Motion 10 |
+| Forms | React Hook Form 7, @hookform/resolvers, Yup |
+| Data & Utils | Axios, dayjs, i18next |
+| Virtualization | react-window, react-window-infinite-loader, react-virtualized-auto-sizer |
+
+### Build Dependencies
+
+| Category | Tools |
+|----------|-------|
+| Build | Vite 6, TypeScript 5, tsc-alias |
+| Quality | ESLint 9, Prettier, Husky, lint-staged |
+
+---
+
+## Next Steps
+
+- [Overview](./01-overview.md) - Project overview and goals
+- [Setup Guide](./02-setup.md) - Setup and development workflows
+- [Component Guide](./04-component-guide.md) - Component catalog and how to choose components
+- [Building Components](./05-component-development.md) - How to create new components and follow patterns

package/docs/04-component-guide.md

@@ -0,0 +1,133 @@
+# Component Guide
+
+Catalog of 100+ components and how to choose the right one. **Avoid duplicating:** check this catalog first, reuse or extend existing components; create new only when necessary. Step-by-step for creating components: [Building Components](./05-component-development.md).
+
+## Building New Components & Avoiding Duplication
+
+1. **Check this catalog** – [Quick Component Finder](#quick-component-finder), [Categories](#component-categories-overview).
+2. **Prefer existing** – Use or compose (e.g. wrap `Input`, `DropdownMenu`); extend with props/variants when possible.
+3. **Create new only when** – No existing component fits and composition isn’t practical. Then follow [05-component-development.md](./05-component-development.md).
+
+## Quick Component Finder
+
+| Need | Component | Notes |
+|------|-----------|--------|
+| Button | `Button` | variant: confirm/cancel, size: small/default |
+| Table (large) | `VirtualTable` | 100+ rows, infinite scroll; needs `Column[]` from `/types` |
+| Table (spreadsheet) | `SheetViewVirtualTable` | Editable, column resize, filters |
+| Text input | `Input` or `RFHInput` | Form → RFHInput; standalone → Input |
+| Dropdown | `DropdownMenu` | options: `{id, label, value}[]` |
+| Dialog | `Dialog`, `SimpleDialog` | open, onClose, title, maxWidth |
+| Loading | `Loader` | size, color |
+| Toast | `useToast` + `<Toaster />` | Hook in component; Toaster at app root |
+| Status badge | `StatusChip` | status: success/warning/error/info |
+| Date | `Calender`, `RFHDatePicker` | Form → RFHDatePicker |
+| Filter | `FilterDropdown` | label, options, value, onChange; optional multiple |
+
+**Import:** `import { ComponentName } from '@tap-payments/os-micro-frontend-shared'` (or `/components`, `/hooks`, etc. – see [Architecture](./03-architecture.md)).
+
+## Component Categories Overview
+
+| Category | Key Components |
+|----------|-----------------|
+| Core UI (20+) | Button, Dialog, Input, Checkbox, Menu, Dropdown, Tooltip |
+| Layout (15+) | AppWindowWrapper, Window, MainContainer, ExpandableSideBar |
+| Data Display (25+) | VirtualTable, SheetViewVirtualTable, Widget, HeatMap, JSONViewer |
+| Forms (20+) | RFHInput, RFHSelect, RFHCheckbox, RFHDatePicker (React Hook Form + Yup) |
+| Filters (15+) | FilterDropdown, DateFilter, StatusFilter, CurrencyFilter, CountryFilter, TreeDropdown |
+| Status & Feedback (10+) | StatusChip, Loader, Toaster, ProgressBar, Error |
+| Media (8+) | LazyImage, FileUpload, FilePreview, ImageWrapper, ReceiptsViewer |
+| Charts (5+) | ActivityAreaChart, HeatMap, TableReports |
+| Specialized (20+) | PaymentSourceFilter, MerchantsDropdown, Amount, DisplayAmount, VAT, Discount |
+
+## Component Reference (compact)
+
+One-line usage; all from `@tap-payments/os-micro-frontend-shared` unless noted.
+
+| Component | Usage / key props |
+|-----------|-------------------|
+| **Core UI** | |
+| Button | `variant="confirm"|"cancel"`, `size`, `onClick` |
+| Dialog | `open`, `onClose`, `title`, `maxWidth`; use DialogContent inside |
+| Input, InputBase | `label`, `value`, `onChange`, `error`, `helperText` |
+| DropdownMenu | `options`, `value`, `onChange`, `placeholder` |
+| Checkbox | `checked`, `onChange`, `label` |
+| Menu, MenuItem | `anchorEl`, `open`, `onClose`; MenuItem `onClick` |
+| Tooltip | `title`, `placement`; wrap trigger |
+| **Layout** | |
+| AppWindowWrapper | `header`, `leftSidebar`, `rightSidebar` + children |
+| MainContainer | Wraps page content |
+| ExpandableSideBar | `sections`, `defaultExpanded` |
+| Window, WindowBackdrop | WindowBackdrop `open`; Window `title`, `onClose` |
+| **Data** | |
+| VirtualTable | `columns`, `data`, `rowHeight`, `height`, `onRowClick`, `hasMore`, `loadMore`, `isLoading`; type `Column` from `/types` |
+| SheetViewVirtualTable | `columns`, `data`, `rowHeight`, `enableColumnResize`, `enableFilters`, `onCellEdit` |
+| Widget, WidgetHeader, WidgetList, ListItem | Compose for dashboard widgets |
+| JSONViewer | `data`, `collapsed`, `enableClipboard`, `theme` |
+| HeatMap | `data` (day, hour, value), `width`, `height`, `colorScheme` |
+| **Forms (RFH)** | `control` from useForm(), `name`, `label`, `rules`; options for Select |
+| RFHInput, RFHSelect, RFHCheckbox, RFHDatePicker | Same pattern: control, name, label, rules |
+| **Filters** | |
+| FilterDropdown | `label`, `options`, `value`, `onChange`, optional `multiple` |
+| DateFilter | `startDate`, `endDate`, `onChange`, `preset` |
+| StatusFilter, CurrencyFilter, CountryFilter | `*s` list, `selected`, `onChange`; CountryFilter `multiple` |
+| TreeDropdown | `data` (id, label, children[]), `selected`, `onChange`, `multiSelect` |
+| **Status** | |
+| StatusChip | `status`, `label`, `size` |
+| Loader | `size`, `color` |
+| Toaster + useToast | `<Toaster />` in app; `useToast()` then `toast.success()`, etc. |
+| ProgressBar | `value`, `max`, `label` |
+| Error | `message`, `onRetry` |
+| **Media** | |
+| LazyImage | `src`, `alt`, `width`, `height`, optional `placeholder` |
+| FileUpload | `accept`, `maxSize`, `onUpload`, `multiple` |
+| FilePreview | `file`, `onRemove`, `onDownload` |
+| **Charts** | |
+| ActivityAreaChart | `data`, `width`, `height`, `xKey`, `yKey` |
+| TableReports | `data`, `columns`, `summary` |
+| **Specialized** | |
+| MerchantsDropdown | `merchants`, `selected`, `onChange` |
+| PaymentSourceFilter | `sources`, `selected`, `onChange` |
+| Amount, DisplayAmount | `value`/`amount`, `currency`; DisplayAmount `conversion` |
+| VAT, Discount | amount/rate; originalPrice/discountedPrice/percentage |
+
+## Component Selection Guide
+
+### Which component to use
+
+| Need | Use |
+|------|-----|
+| Tabular 100+ rows | VirtualTable |
+| Tabular editable / resize | SheetViewVirtualTable |
+| Input in form | RFHInput, RFHSelect, RFHCheckbox, RFHDatePicker |
+| Input standalone | Input, DropdownMenu, Checkbox |
+| Status static | StatusChip |
+| Loading | Loader |
+| Notification | Toaster + useToast |
+| Layout full page | AppWindowWrapper |
+| Layout section | MainContainer, Widget |
+| Sidebar | ExpandableSideBar |
+| Modal | Dialog, SimpleDialog, ConfirmDialog |
+| Filter date | DateFilter |
+| Filter options | FilterDropdown |
+| Filter tree | TreeDropdown |
+| Image | LazyImage |
+| File | FileUpload, FilePreview |
+
+### VirtualTable vs SheetViewVirtualTable
+
+| | VirtualTable | SheetViewVirtualTable |
+|--|--------------|------------------------|
+| Rows | 100+ (virtualized) | Any (virtualized) |
+| Infinite scroll | ✓ | ✓ |
+| Inline edit | ✗ | ✓ |
+| Column resize | — | ✓ |
+
+### RFH vs regular inputs
+
+- **RFH** (RFHInput, RFHSelect, …): forms with validation, React Hook Form, Yup.
+- **Regular** (Input, DropdownMenu, …): standalone, no RHF, or custom form lib.
+
+## Next Steps
+
+- [Overview](./01-overview.md) · [Setup](./02-setup.md) · [Architecture](./03-architecture.md) · [Building Components](./05-component-development.md)