🌟 Macross UserInfo Library

A modern React TypeScript library for displaying user information components with beautiful, responsive design code structure.

📋 Table of Contents

• Features
• Prerequisites
• Installation & Setup
• Development
• Project Structure
• Component Usage
• API Configuration
• Build & Deployment
• Git Workflow
• Contributing
• Troubleshooting

✨ Features

• 🎨 Modern Design - Clean, responsive UI components
• 📱 Mobile Friendly - Optimized for all screen sizes
• 🔧 TypeScript - Full type safety and IntelliSense support
• 🎯 Modular Components - 11 separate reusable components
• 🌐 Japanese Support - Built-in Japanese font stack
• ⚡ Fast Development - Vite for lightning-fast builds
• 📦 NPM Ready - Publishable as NPM package
• 🎨 SCSS Modules - Component-scoped styling

🛠 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (version 16.0.0 or higher)
• npm (version 8.0.0 or higher) or yarn (version 1.22.0 or higher)
• Git (version 2.0.0 or higher)

Check Your Versions

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Git version
git --version

🚀 Installation & Setup

Step 1: Clone the Repository

# Clone the repository from Git
git clone ssh://[email protected]:7999/macross/macross-userinfo.git

# Navigate to the project directory
cd macross-userinfo

Step 2: Install Dependencies

# Install all project dependencies
npm install

# Alternative: If you prefer yarn
yarn install

Step 3: Environment Setup

The project comes pre-configured, but you can customize settings in:

• vite.config.ts - Build configuration
• tsconfig.json - TypeScript settings
• package.json - Project metadata

💻 Development

Start Development Server

# Start the development server (opens browser automatically)
npm run dev

# Alternative development modes
npm run dev:staging    # Staging environment
npm run dev:production # Production environment

The application will be available at:

• Local: http://localhost:5174/ (or next available port)
• Network: Available on your local network IP

Development Features

• 🔥 Hot Module Replacement - Changes reflect instantly
• 🎯 TypeScript Checking - Real-time error detection
• 🎨 SCSS Processing - Modern CSS with variables and nesting
• 📱 Responsive Preview - Test on different screen sizes

📁 Project Structure

macross-userinfo/
├── 📁 src/
│   ├── 📁 components/          # All React components
│   │   ├── 📁 UserInfo/        # Main UserInfo component
│   │   ├── 📁 Close/           # Close button component
│   │   ├── 📁 AvailablePoints/ # Points display component
│   │   ├── 📁 LimitedTimePoints/ # Limited time points
│   │   └── ... (8 more components)
│   ├── 📁 apiservices/         # API service functions
│   │   ├── 📁 mock/            # Mock data for testing
│   │   └── UserAPI.ts          # User data API
│   ├── 📁 assets/              # SVG icons and images
│   ├── 📁 types/               # TypeScript type definitions
│   ├── 📁 styles/              # Global SCSS styles
│   ├── App.tsx                 # Main application component
│   ├── main.tsx               # Application entry point
│   └── lib.tsx                # Library exports
├── 📁 dist/                   # Built files (generated)
├── 📄 package.json            # Project configuration
├── 📄 vite.config.ts          # Vite build configuration
├── 📄 tsconfig.json           # TypeScript configuration
└── 📄 README.md               # This file

🎯 Component Usage

Basic UserInfo Component

import React from 'react';
import { UserInfo } from '@macross/userinfo';

function App() {
  return (
    <div className="app">
      <UserInfo 
        user={{
          name: "楽天太郎",
          membershipStatus: "ダイヤモンド会員",
          availablePoints: 29999,
          limitedTimePoints: 1850
        }}
      />
    </div>
  );
}

Available Components

• UserInfo - Main container component
• Close - Close button with callback
• AvailablePoints - Display available points
• LimitedTimePoints - Show limited time points
• MemberRank - Rank and status
• YesterdayPoint - Yesterday's points
• MonthlyPoint - Monthly point totals
• Points - Points section header
• MemberInfo - Member information header
• PointAcquisitionHistory - Point history with navigation
• MembershipInfo - Membership information with navigation
• Logout - Logout button with callback

🔌 API Configuration

Mock API (Development)

The project includes mock APIs for development:

// Available mock functions
import { fetchUserInfo } from './apiservices/mock/UserAPI';

// Example usage
const userData = await fetchUserInfo();

Production API

Update the API endpoints in src/apiservices/UserAPI.ts:

// Replace with your production API endpoints
const API_BASE_URL = 'https://your-api-domain.com';

export const fetchUserInfo = async (): Promise<RakutenUserResponse> => {
  // Your production API implementation
};

🏗 Build & Deployment

Development Build

npm run build:dev

Staging Build

npm run build:staging

Production Build

npm run build:production

Type Checking

# Check TypeScript types without building
npm run type-check

Preview Production Build

# Build and preview the production version
npm run preview

🔄 Git Workflow

Basic Git Commands

1. Check Current Status

git status

2. Create a New Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Example
git checkout -b feature/update-user-profile

3. Make Changes and Commit

# Add all changes
git add .

# Or add specific files
git add src/components/UserInfo.tsx

# Commit with a descriptive message
git commit -m "Add new user profile component"

4. Push Changes

# Push to your branch
git push origin feature/your-feature-name

5. Switch Between Branches

# Switch to main branch
git checkout main

# Switch back to your feature branch
git checkout feature/your-feature-name

6. Pull Latest Changes

# Get latest changes from main
git checkout main
git pull origin main

Branch Naming Convention

• feature/ - New features (e.g., feature/add-logout-button)
• bugfix/ - Bug fixes (e.g., bugfix/fix-points-display)
• hotfix/ - Critical fixes (e.g., hotfix/security-patch)
• update/ - Updates (e.g., update/dependencies)

🤝 Contributing

Development Guidelines

1. Code Style

   • Use TypeScript for all new code
   • Follow existing naming conventions
   • Add comments for complex logic
   • Use SCSS modules for styling

2. Component Guidelines

   • Keep components small and focused
   • Use props interfaces for type safety
   • Include default props where appropriate

3. Testing Your Changes

   # Start development server
   npm run dev
      
   # Check for TypeScript errors
   npm run type-check
      
   # Build to ensure no build errors
   npm run build

🆘 Troubleshooting

Common Issues

Port Already in Use

# The dev server will automatically find the next available port
# Check the terminal output for the actual port number

Sass Deprecation Warnings

The project is configured to handle Sass warnings. If you see them:

# The warnings are suppressed in vite.config.ts
# They don't affect functionality

TypeScript Errors

# Check your code for type issues
npm run type-check

# Common fixes:
# 1. Import types properly
# 2. Add type annotations
# 3. Check for typos in property names

Build Failures

# Clean the dist folder and rebuild
npm run clean
npm run build

Git Issues

# Check current branch and status
git status

# If you have merge conflicts, resolve them manually
# Then commit the resolved files
git add .
git commit -m "Resolve merge conflicts"

Getting Help

• 📧 Contact: Jithern Thomas (Project Author)
• 🐛 Issues: Report bugs via Git repository
• 📖 Documentation: Check this README and inline code comments

📝 Scripts Reference

| Command | Description | |---------|-------------| | npm run dev | Start development server | | npm run build | Build for production | | npm run preview | Preview production build | | npm run type-check | Check TypeScript types | | npm run clean | Clean build directory | | npm publish | Publish to NPM |

📄 License

MIT License - see the LICENSE file for details.

🏷 Version

Current version: 0.1.0

Happy coding! 🚀