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

package/build/utils/merchantSource.d.ts

@@ -1,4 +1,4 @@
-import { TextAndLang } from '../types/index.js';
+import { TextAndLang } from '@types';
 interface Source {
     code: string;
     name: TextAndLang[];

package/build/utils/navigation.d.ts

@@ -1,12 +1,12 @@
-import { AppDetails, UserApp } from '../types/index.js';
+import { AppDetails, UserApp } from '@types';
 export declare const getApp: (apps: UserApp[], appCode: string) => UserApp | undefined;
-export declare const getService: (services: UserApp['app_services'], serviceCode: string) => import("../types/index.js").AppService | undefined;
+export declare const getService: (services: UserApp['app_services'], serviceCode: string) => import("@types").AppService | undefined;
 export declare const openNewAppAttrs: ({ appCode, serviceCode, sandboxMode, payload, segmentId, numberOfOpenedApps, }: Pick<AppDetails, "appCode" | "serviceCode" | "payload"> & {
     sandboxMode?: boolean | undefined;
     numberOfOpenedApps: number;
     segmentId: string;
 }) => {
-    payload?: (Record<string, any> & Omit<import("../types/index.js").DefaultServicePayload, never> & object) | undefined;
+    payload?: (Record<string, any> & Omit<import("@types").DefaultServicePayload, never> & object) | undefined;
     segmentId: string;
     appCode: string;
     serviceCode: string;

package/build/utils/segment.d.ts

@@ -1,4 +1,4 @@
-import { SelectedSegment, Segment, SegmentData } from '../types/index.js';
+import { SelectedSegment, Segment, SegmentData } from '@types';
 export declare const getSegmentData: (segments: Segment[], activeSegmentId: string, activeSegments: SelectedSegment[]) => SegmentData;
 export declare const getBusinessSegmentConfig: ({ merchantsIds, options }: {
     merchantsIds: string[];

package/build/utils/skeletonColumns.d.ts

@@ -1,4 +1,4 @@
-import type { IColumnProps } from '../types/index.js';
+import type { IColumnProps } from '@types';
 export declare const DEFAULT_SKELETON_WIDTHS: string[];
 export declare const generateSkeletonColumns: (staticWidths?: string[]) => IColumnProps[];
 export declare const getProcessedColumns: <T = unknown>(columns: readonly IColumnProps<T>[], isLoading: boolean, defaultSkeleton: boolean) => IColumnProps<T>[];

package/build/utils/table.d.ts

@@ -1,4 +1,4 @@
-import { TableCellWidthProps, TableMode, TableNavigation } from '../types/index.js';
+import { TableCellWidthProps, TableMode, TableNavigation } from '@types';
 export declare const getColumnWidthPercentage: (widthInPx: number, options?: {
     isFirst?: boolean;
     isLast?: boolean;

package/build/utils/views.d.ts

@@ -1,2 +1,2 @@
-import type { Template } from '../components/TableHeader';
+import type { Template } from '../src/components/TableHeader';
 export declare const updateViewsSelection: (templates: Template[], columnsSelection: Record<string, boolean>) => Template[];

package/docs/.storybook/main.ts

@@ -0,0 +1,23 @@
+import type { StorybookConfig } from '@storybook/react-vite'
+// vite-tsconfig-paths plugin so all @components, @theme, @types, etc. aliases work inside stories
+import tsconfigPaths from 'vite-tsconfig-paths'
+import { mergeConfig } from 'vite'
+
+const config: StorybookConfig = {
+  stories: ['../stories/**/*.stories.@(ts|tsx|mdx)'],
+  addons: ['@storybook/addon-a11y', '@storybook/addon-docs'],
+
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+
+  // Resolve the same path aliases used in tsconfig.json (@components, @theme, etc.)
+  viteFinal: async (config) => {
+    return mergeConfig(config, {
+      plugins: [tsconfigPaths()],
+    })
+  }
+}
+
+export default config

package/docs/.storybook/preview.tsx

@@ -0,0 +1,106 @@
+import React from 'react'
+import type { Preview, Decorator } from '@storybook/react-vite'
+import CssBaseline from '@mui/material/CssBaseline'
+import { appTheme } from '../../src/theme'
+import { ThemeMode } from '../../src/types/theme'
+import MUIThemeProvider from '../../src/components/MUIThemeProvider'
+import { initReactI18next } from 'react-i18next'
+import i18n from 'i18next'
+
+// ---------------------------------------------------------------------------
+// Minimal i18n setup so components that call useTranslation() don't crash.
+// Stories that need real translations can override this in their decorator.
+// ---------------------------------------------------------------------------
+if (!i18n.isInitialized) {
+  i18n.use(initReactI18next).init({
+    lng: 'en',
+    fallbackLng: 'en',
+    resources: { en: { translation: {} } },
+    interpolation: { escapeValue: false },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Toolbar: Theme (light / dark) + Direction (ltr / rtl)
+// ---------------------------------------------------------------------------
+export const globalTypes = {
+  themeMode: {
+    name: 'Theme',
+    description: 'MUI theme mode',
+    defaultValue: 'light',
+    toolbar: {
+      icon: 'circlehollow',
+      items: [
+        { value: 'light', title: 'Light', icon: 'sun' },
+        { value: 'dark', title: 'Dark', icon: 'moon' },
+      ],
+      dynamicTitle: true,
+    },
+  },
+  direction: {
+    name: 'Direction',
+    description: 'Text direction (LTR / RTL)',
+    defaultValue: 'ltr',
+    toolbar: {
+      icon: 'menu',
+      items: [
+        { value: 'ltr', title: 'LTR' },
+        { value: 'rtl', title: 'RTL' },
+      ],
+      dynamicTitle: true,
+    },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Global decorator — wraps every story with the correct MUI theme
+// ---------------------------------------------------------------------------
+const withMUITheme: Decorator = (Story, context) => {
+  const mode = (context.globals.themeMode as ThemeMode) ?? ThemeMode.LIGHT
+  const direction = (context.globals.direction as 'ltr' | 'rtl') ?? 'ltr'
+  const theme = appTheme(mode, direction)
+
+  return (
+    <MUIThemeProvider theme={theme}>
+      <CssBaseline />
+      <div dir={direction} style={{ padding: '1.5rem' }}>
+        <Story />
+      </div>
+    </MUIThemeProvider>
+  )
+}
+
+const preview: Preview = {
+  decorators: [withMUITheme],
+
+  parameters: {
+    // Default backgrounds synced with the theme selector
+    backgrounds: {
+      options: {
+        light: { name: 'light', value: '#ffffff' },
+        dark: { name: 'dark', value: '#121212' }
+      }
+    },
+
+    controls: {
+      // Show default values in the Controls panel
+      expanded: true,
+      // Sort alphabetically for easier scanning
+      sort: 'alpha',
+      matchers: {
+        color: /(color|background|bg|fill)$/i,
+        date: /date$/i,
+      },
+    },
+
+    actions: { argTypesRegex: '^on[A-Z].*' },
+  },
+
+  initialGlobals: {
+    backgrounds: {
+      value: 'light'
+    }
+  }
+}
+
+export default preview

package/docs/.storybook/story-utils.tsx

@@ -0,0 +1,196 @@
+/**
+ * story-utils.tsx
+ *
+ * Shared layout primitives for .stories.tsx files.
+ * Import from any story:
+ *   import { StoryTable, StoryFlexRow, ... } from '../../.storybook/story-utils'
+ *
+ * All components use MUI sx + theme tokens so they adapt to the
+ * light/dark toolbar toggle in preview.tsx automatically.
+ *
+ * Rule: add exports here only when a pattern appears in 2+ stories.
+ *
+ * CONVENTION — stateful stories (render + useState):
+ * When a story uses a `render` function with `useState`, Storybook cannot
+ * auto-generate useful "Show code" output. Always add an explicit source
+ * override so developers can copy real usage:
+ *
+ *   parameters: {
+ *     docs: {
+ *       source: {
+ *         language: 'tsx',
+ *         code: `...clean minimal snippet...`.trim(),
+ *       },
+ *     },
+ *   },
+ */
+import React from 'react'
+import Box, { type BoxProps } from '@mui/material/Box'
+import Stack, { type StackProps } from '@mui/material/Stack'
+import Typography, { type TypographyProps } from '@mui/material/Typography'
+
+// ─── Spacing tokens ──────────────────────────────────────────────────────────
+// Named constants so story authors never write magic numbers.
+// Values map to theme.spacing() units (1 unit = 8px by default in MUI).
+export const STORY_SPACING = {
+  cell: 2, // 16px — cell padding
+  labelRight: 3, // 24px — right-pad on row/column label cells
+  section: 4, // 32px — gap between table and hint text
+} as const
+
+// ─── Table primitives ─────────────────────────────────────────────────────────
+
+export function StoryTable({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box
+      component="table"
+      sx={[
+        {
+          width: '100%',
+          borderCollapse: 'separate',
+          borderSpacing: '0 10px',
+          fontSize: '1rem',
+          tableLayout: 'auto',
+        },
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  )
+}
+
+export function StoryThead({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box component="thead" sx={sx} {...rest}>
+      {children}
+    </Box>
+  )
+}
+
+export function StoryTbody({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box component="tbody" sx={sx} {...rest}>
+      {children}
+    </Box>
+  )
+}
+
+export function StoryRow({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box
+      component="tr"
+      sx={[
+        (theme) => ({
+          '&:hover td': {
+            backgroundColor: theme.palette.action.hover,
+          },
+        }),
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  )
+}
+
+// `first` targets the leftmost header cell (row label column) — left-aligned.
+export function StoryHeaderCell({ first = false, children, sx, ...rest }: BoxProps & { first?: boolean }) {
+  return (
+    <Box
+      component="th"
+      sx={[
+        (theme) => ({
+          padding: first ? theme.spacing(0.5, STORY_SPACING.labelRight, 0.5, 0) : theme.spacing(0.5, STORY_SPACING.cell),
+          fontWeight: theme.typography.fontWeightMedium,
+          fontSize: '1.1rem',
+          color: theme.palette.text.primary,
+          whiteSpace: 'nowrap',
+          textAlign: 'left',
+        }),
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  )
+}
+
+export function StoryRowLabel({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box
+      component="th"
+      sx={[
+        (theme) => ({
+          textAlign: 'left',
+          padding: theme.spacing(STORY_SPACING.cell, STORY_SPACING.labelRight, STORY_SPACING.cell, 0),
+          fontWeight: theme.typography.fontWeightRegular,
+          fontSize: '1.1rem',
+          color: theme.palette.text.primary,
+          verticalAlign: 'middle',
+          whiteSpace: 'nowrap',
+        }),
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  )
+}
+
+export function StoryCell({ children, sx, ...rest }: BoxProps) {
+  return (
+    <Box
+      component="td"
+      sx={[
+        (theme) => ({
+          padding: theme.spacing(STORY_SPACING.cell),
+          textAlign: 'center',
+          verticalAlign: 'middle',
+          borderBottom: `1px solid ${theme.palette.divider}`,
+        }),
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  )
+}
+
+// ─── Flex row ─────────────────────────────────────────────────────────────────
+
+// Default spacing={3} = 24px. Pass spacing={1} (8px) for tighter layouts.
+export function StoryFlexRow({ children, sx, ...rest }: StackProps) {
+  return (
+    <Stack direction="row" alignItems="center" spacing={3} sx={sx} {...rest}>
+      {children}
+    </Stack>
+  )
+}
+
+// ─── Hint text ────────────────────────────────────────────────────────────────
+
+export function StoryHint({ children, sx, ...rest }: TypographyProps) {
+  return (
+    <Typography
+      variant="caption"
+      align="center"
+      sx={[
+        (theme) => ({
+          display: 'block',
+          mt: STORY_SPACING.section,
+          color: theme.palette.text.secondary,
+        }),
+        ...(Array.isArray(sx) ? sx : [sx]),
+      ]}
+      {...rest}
+    >
+      {children}
+    </Typography>
+  )
+}

package/docs/01-overview.md

@@ -0,0 +1,158 @@
+# Project Overview
+
+## OS Micro Frontend Shared
+
+React component library for Tap Payments providing unified UI components, hooks, and utilities for micro frontend applications.
+
+## Core Capabilities
+
+- **UI Components**: 100+ production-ready components (buttons, tables, dialogs, forms, filters)
+- **Data Virtualization**: High-performance virtual tables for large datasets with infinite scroll
+- **Form Management**: React Hook Form integration with validation schemas
+- **Theme System**: MUI-based theming with dark/light mode and RTL/LTR support
+- **Hooks & Utilities**: Custom React hooks and helper functions for common tasks
+- **Type Safety**: Comprehensive TypeScript definitions for all exports
+
+## Key Features
+
+| Feature              | Description                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| Component Library    | 100+ React components organized by feature and use case          |
+| Virtual Tables       | react-window based tables for 1000+ rows with optimal rendering |
+| Form Components      | React Hook Form wrappers with Yup validation support            |
+| Theme Support        | Dark/light mode, RTL/LTR direction, customizable MUI theme      |
+| ESM Only             | Modern ES modules for optimal tree-shaking                       |
+| Peer Dependencies    | Prevents version conflicts and bundle bloat                      |
+| TypeScript           | Full type safety with .d.ts files for all exports               |
+| Path Aliases         | Clean imports in source code with build-time resolution          |
+
+## Package Information
+
+| Attribute      | Description                                              | Value                                                    |
+| -------------- | -------------------------------------------------------- | -------------------------------------------------------- |
+| Package Name   | NPM package identifier                                   | `@tap-payments/os-micro-frontend-shared`                 |
+| Type           | Module format and purpose                                | React Component Library (ESM)                            |
+| Registry       | Package distribution                                     | npm (public)                                             |
+| Import Example | How to use in your app                                   | `import { Button, useToast } from '@tap-payments/...'` |
+
+## Key Features & Capabilities
+
+### Component Library
+- **100+ React components** organized by feature
+- MUI-based with custom styling
+- Supports dark/light themes
+- RTL/LTR direction support
+- Memoized for performance
+
+### Virtual Tables
+- High-performance virtualized lists
+- Infinite scroll support
+- Sheet view and standard table views
+- Column resizing and filtering
+
+### Form Components
+- React Hook Form integration (`RFH/` folder)
+- Input components with validation
+- Yup schema support
+
+### Utility Modules
+- API utilities, date/currency formatting
+- Local storage helpers
+- Validation utilities
+- Error handling
+
+## Tech Stack
+
+| Technology                  | Purpose                                      | Version |
+| --------------------------- | -------------------------------------------- | ------- |
+| React                       | UI framework and component architecture      | 18.x    |
+| TypeScript                  | Type safety and developer experience         | 5.0.x   |
+| MUI (Material-UI)           | Component base and design system             | 5.x     |
+| Emotion                     | CSS-in-JS styling with theme support         | 11.x    |
+| React Hook Form             | Form state management and validation         | 7.x     |
+| Yup                         | Schema validation for forms                  | 1.x     |
+| react-window                | List virtualization for performance          | 1.8.x   |
+| Framer Motion               | Animations and transitions                   | 10.x    |
+| Vite                        | Build tool and dev server                    | 6.x     |
+
+## Architecture
+
+**Module Pattern**:
+
+```mermaid
+flowchart LR
+  A[Consumer App] --> B[Package Entry]
+  B --> C[Module Index]
+  C --> D[Components / Hooks / Utils]
+  B --> E[Theme]
+  E --> F[MUI Components]
+```
+
+**Responsibilities**:
+
+- **Components**: UI elements with props interface and styled components
+- **Hooks**: Custom React hooks for state management and side effects
+- **Utils**: Pure functions for formatting, validation, and data manipulation
+- **Types**: TypeScript interfaces and type definitions
+- **Constants**: Static configuration values and enums
+- **Theme**: MUI theme factory with palette, typography, and component overrides
+
+## Component Categories
+
+### Virtual Tables (Performance-Critical)
+- `VirtualTable` - Main virtualized table for 1000+ rows
+- `SheetViewVirtualTable` - Spreadsheet-style with inline editing
+
+### Forms & Inputs (React Hook Form)
+- `RFHInput`, `RFHSelect`, `RFHCheckbox` - Form-integrated inputs
+- `RFHDatePicker` - Date selection with validation
+- Yup schema validation support
+
+### Dialogs & Modals
+- `Dialog`, `SimpleDialog` - Modal overlays
+- `ConfirmDialog` - Confirmation with provider pattern
+- `Window`, `WindowBackdrop` - Floating window system
+
+### Filters & Dropdowns
+- `FilterDropdown` - Multi-select filtering
+- `DateFilter`, `StatusFilter`, `CurrencyFilter` - Domain filters
+- `TreeDropdown` - Hierarchical selection
+
+### Layout & Structure
+- `AppWindowWrapper` - Full-page layout container
+- `MainContainer` - Content wrapper
+- `ExpandableSideBar` - Collapsible navigation
+
+### Status & Feedback
+- `StatusChip` - Status badges
+- `Loader`, `Toaster` - Loading and notifications
+- `ProgressBar`, `Error` - Progress and error states
+
+
+## Use Cases
+
+1. **Micro Frontend UI**: Shared components ensure consistent design across all Tap Payments apps
+2. **Large Data Tables**: Virtual tables handle 10,000+ rows with smooth scrolling performance
+3. **Form Management**: RHF components with validation reduce boilerplate in consumer apps
+4. **Theme Consistency**: Centralized MUI theme ensures brand consistency and supports dark mode
+5. **Type Safety**: TypeScript definitions catch errors at compile time across all consuming apps
+
+## Import Patterns
+
+```typescript
+// Main entry - everything
+import { Button, VirtualTable, useToast } from '@tap-payments/os-micro-frontend-shared'
+
+// Specific modules - better tree-shaking
+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'
+```
+
+## Next Steps
+
+- [Setup Guide](./02-setup.md) - Installation and development commands
+- [Architecture](./03-architecture.md) - Detailed system design
+- [Component Guide](./04-component-guide.md) - Component catalog and selection
+- [Building Components](./05-component-development.md) - How to create new components