npm package: @mehdashti/react-core
Description: Core React providers and hooks for Smart Platform applications
Author: mehdashti
Latest version: 0.1.1

# @mehdashti/react-core

Core React providers and hooks for Smart Platform applications.

## Installation

```bash
pnpm add @mehdashti/react-core
```

## Features

- **ThemeProvider**: Dark/light theme management with RTL support
- **QueryProvider**: TanStack Query client setup with optimized defaults
- **ErrorBoundary**: Global error handling with fallback UI
- **AppConfigProvider**: Application configuration management
- **AppProviders**: Convenient wrapper combining all providers

## Usage

### Quick Start

Wrap your app with `AppProviders`:

```tsx
import { AppProviders } from '@mehdashti/react-core'
import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <AppProviders queryClient={queryClient}>
      <YourApp />
    </AppProviders>
  )
}
```

### ThemeProvider

```tsx
import { ThemeProvider, useTheme } from '@mehdashti/react-core'

function ThemeToggle() {
  const { theme, setTheme, isDark } = useTheme()

  return (
    <button onClick={() => setTheme(isDark ? 'light' : 'dark')}>
      Toggle theme
    </button>
  )
}

function App() {
  return (
    <ThemeProvider defaultTheme="system" defaultDirection="ltr">
      <ThemeToggle />
    </ThemeProvider>
  )
}
```

### ErrorBoundary

```tsx
import { ErrorBoundary } from '@mehdashti/react-core'

function App() {
  return (
    <ErrorBoundary
      fallback={(error) => (
        <div>Error: {error.message}</div>
      )}
      onError={(error, errorInfo) => {
        console.error('Error caught:', error, errorInfo)
      }}
    >
      <YourApp />
    </ErrorBoundary>
  )
}
```

### AppConfigProvider

```tsx
import { AppConfigProvider, useAppConfig } from '@mehdashti/react-core'

function ConfigDisplay() {
  const { config, updateConfig } = useAppConfig()

  return (
    <div>
      <p>API URL: {config.apiUrl}</p>
      <button onClick={() => updateConfig({ apiUrl: 'https://new-api.com' })}>
        Update API URL
      </button>
    </div>
  )
}

function App() {
  return (
    <AppConfigProvider initialConfig={{ apiUrl: 'https://api.example.com' }}>
      <ConfigDisplay />
    </AppConfigProvider>
  )
}
```

## API

### Providers

#### `AppProviders`

Combines all providers in one component.

**Props:**
- `children: ReactNode` - Your application
- `queryClient?: QueryClient` - TanStack Query client (optional)
- `theme?: ThemeProviderProps` - Theme provider config (optional)
- `errorBoundary?: ErrorBoundaryProps` - Error boundary config (optional)
- `appConfig?: AppConfigProviderProps` - App config provider config (optional)

#### `ThemeProvider`

**Props:**
- `children: ReactNode`
- `defaultTheme?: 'light' | 'dark' | 'system'` (default: `'system'`)
- `defaultDirection?: 'ltr' | 'rtl'` (default: `'ltr'`)
- `storageKey?: string` (default: `'smart-platform-theme'`)

#### `QueryProvider`

**Props:**
- `children: ReactNode`
- `queryClient?: QueryClient` - Custom query client (optional, creates default if not provided)

#### `ErrorBoundary`

**Props:**
- `children: ReactNode`
- `fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode)` - Custom fallback UI
- `onError?: (error: Error, errorInfo: ErrorInfo) => void` - Error callback

#### `AppConfigProvider`

**Props:**
- `children: ReactNode`
- `initialConfig?: AppConfig` - Initial configuration

### Hooks

#### `useTheme()`

Returns:
- `theme: 'light' | 'dark' | 'system'` - Current theme
- `setTheme: (theme) => void` - Update theme
- `direction: 'ltr' | 'rtl'` - Current direction
- `setDirection: (direction) => void` - Update direction
- `isDark: boolean` - Whether dark theme is active
- `isRTL: boolean` - Whether RTL is active

#### `useAppConfig()`

Returns:
- `config: AppConfig` - Current configuration
- `updateConfig: (config) => void` - Update configuration

## Types

```typescript
export type ThemeMode = 'light' | 'dark' | 'system'
export type Direction = 'ltr' | 'rtl'

export interface AppConfig {
  appName?: string
  apiUrl?: string
  enableDevTools?: boolean
  [key: string]: unknown
}
```

## License

MIT