🎫 AM Ticket System

A complete React ticket/messaging system component library with Persian authentication, custom modals, and professional UI/UX.

✨ Features

• 🔐 Persian Authentication - Built-in mobile OTP authentication
• 🎨 Custom Modals - Professional modal system with React portals
• 📱 Responsive Design - Mobile-first with full RTL support
• 🎯 TypeScript - Full type safety
• 🚀 Zero Config - Works out of the box
• 💬 Real-time Messaging - Live ticket updates
• 📎 File Upload - Drag & drop file support
• 🌐 i18n Ready - Persian/English support

📦 Installation

npm install am-ticket-system
# or
yarn add am-ticket-system
# or
pnpm add am-ticket-system

Peer Dependencies

Make sure you have React and ReactDOM installed:

npm install react react-dom

🎨 Styles & CSS

This package includes custom utility CSS classes (not Tailwind CSS). Styles are automatically injected into your bundle!

// ✅ Automatic - styles are injected (recommended)
import { TicketSystem } from 'am-ticket-system'

// 📦 Optional - manual CSS import (if needed)
import 'am-ticket-system/dist/styles.css'

No configuration needed! The CSS is bundled and auto-injected.

📚 For detailed styling guide, customization, and framework-specific setup, see STYLES_GUIDE.md.

🚀 Quick Start

1. Use FloatingTicketButton

import { FloatingTicketButton } from 'am-ticket-system'
// No CSS import needed - styles auto-inject!

function App() {
  return (
    <div>
      <h1>My App</h1>

      <FloatingTicketButton
        apiUrl="https://your-api.com"
        requireAuth={true}
        allowGuestMode={false}
      />
    </div>
  )
}

3. Use TicketSystem Component

import { TicketSystem } from 'am-ticket-system'
// Styles are auto-injected, no CSS import needed

function SupportPage() {
  return (
    <div style={{ height: '100vh' }}>
      <TicketSystem
        apiUrl="https://your-api.com"
        requireAuth={true}
        theme="light"
      />
    </div>
  )
}

📖 Documentation

FloatingTicketButton Props

interface FloatingTicketButtonProps {
  // API Configuration
  apiUrl: string
  uploadUrl?: string
  mediaUrl?: string

  // Authentication
  requireAuth?: boolean
  autoLogin?: boolean
  allowGuestMode?: boolean
  tokenKey?: string

  // UI Customization
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  theme?: 'light' | 'dark'
  size?: 'small' | 'medium' | 'large'
  showBadge?: boolean
  customIcon?: React.ReactNode

  // Callbacks
  onAuthStateChange?: (isAuthenticated: boolean, user: User | null) => void
  onLoginSuccess?: (user: User, token: string) => void
  onLoginError?: (error: Error) => void
  onLogout?: () => void
}

TicketSystem Props

interface TicketSystemProps {
  // API Configuration (Required)
  apiUrl: string

  // File Upload
  uploadUrl?: string
  mediaUrl?: string

  // Authentication
  requireAuth?: boolean
  autoLogin?: boolean
  allowGuestMode?: boolean

  // UI
  theme?: 'light' | 'dark'
  rtl?: boolean

  // Callbacks
  onAuthStateChange?: (isAuthenticated: boolean, user: User | null) => void
  onMessageReceived?: (message: TicketMessage) => void
  onError?: (error: Error) => void
}

🎨 Customization

Custom Theme

You can override CSS variables:

:root {
  --ticket-primary: #007bff;
  --ticket-primary-hover: #0056b3;
  --ticket-bg: #ffffff;
  --ticket-text: #212529;
}

Dark Theme

<TicketSystem apiUrl="https://api.example.com" theme="dark" />

📱 Mobile Support

The library is fully responsive and mobile-friendly:

• Full-screen modals on mobile
• Touch-friendly buttons
• Optimized for Persian (RTL) layout
• Prevents zoom on inputs

🔐 Authentication Flow

1. User clicks support button
2. If not authenticated:
   • Auth modal opens
   • User enters mobile number
   • Receives OTP code
   • Enters OTP
   • Auth modal closes
   • Ticket modal opens
3. If authenticated:
   • Ticket modal opens directly

📦 What's Included

Components

• TicketSystem - Main ticket interface
• FloatingTicketButton - Floating support button
• CustomTicketModal - Modal system
• AuthModalContent - Authentication UI
• PersianAuthWrapper - Auth wrapper
• MobileLoginForm - Mobile login
• OtpForm - OTP verification
• CreateTicketModal - Create ticket
• All messaging components

Hooks

• usePersianAuth - Authentication logic
• useTicketSystem - Ticket management
• useFileUpload - File upload handling
• useVirtualScroll - Performance optimization

Utilities

• translateStatus - Status translations
• translatePriority - Priority translations
• getStatusColor - Status colors
• Cookie management
• Persian tools

🌐 API Integration

Your API should implement these endpoints:

// Authentication
POST /v1/user/login { mobile: string }
POST /v1/user/verify { mobile: string, otp: string }
GET /v1/user (with Bearer token)

// Tickets
GET /v1/user/tickets
POST /v1/user/tickets
GET /v1/user/tickets/:id
POST /v1/user/tickets/:id/messages

// File Upload
POST /v1/upload-v1

🔧 Advanced Usage

With Custom Auth Callbacks

<FloatingTicketButton
  apiUrl="https://api.example.com"
  requireAuth={true}
  onLoginSuccess={(user, token) => {
    console.log('User logged in:', user)
    // Store in your state management
  }}
  onLogout={() => {
    console.log('User logged out')
    // Clear your state
  }}
  onAuthStateChange={(isAuthenticated, user) => {
    console.log('Auth state changed:', isAuthenticated, user)
  }}
/>

Standalone Components

import { CustomTicketModal, AuthModalContent } from 'am-ticket-system'

function MyCustomAuth() {
  const [showAuth, setShowAuth] = useState(true)

  return (
    <CustomTicketModal isOpen={showAuth} onClose={() => setShowAuth(false)}>
      <AuthModalContent
        apiUrl="https://api.example.com"
        onAuthSuccess={() => {
          setShowAuth(false)
          // Handle success
        }}
        onClose={() => setShowAuth(false)}
      />
    </CustomTicketModal>
  )
}

🐛 Troubleshooting

CSS Not Loading

Make sure you import the CSS file:

// Styles are auto-injected, no CSS import needed

TypeScript Errors

The package includes TypeScript definitions. Make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Build Errors

If you get build errors, make sure you have all peer dependencies:

npm install react react-dom

📝 License

MIT © Amin Mohseni

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

For issues and questions:

• GitHub Issues: Report a bug
• Email: [email protected]

🔄 Changelog

See CHANGELOG.md for version history.

Made with ❤️ for Persian developers