create-bluecopa-react-app 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# Create BlueCopa React App
+
+A CLI tool to bootstrap modern React applications for BlueCopa with built-in UI components, data visualization capabilities, and development best practices.
+
+## Features
+
+- 🚀 **Modern React Stack**: React 18, TypeScript, Vite
+- 📊 **Data Visualization**: Integration ready for charts and analytics
+- 🎨 **UI Components**: shadcn/ui with Radix UI primitives  
+- 📡 **BlueCopa React Components**: Pre-configured @bluecopa/react package
+- 🎯 **Type Safety**: Full TypeScript support
+- 📱 **Responsive Design**: Tailwind CSS with mobile-first approach
+- 🛠️ **Development Tools**: ESLint, TypeScript checking, and modern build tools
+
+## Quick Start
+
+```bash
+# Install the CLI tool globally
+npm install -g create-bluecopa-react-app
+
+# Create a new BlueCopa React app
+create-bluecopa-react-app my-dashboard
+
+# Or use npx (no global installation needed)
+npx create-bluecopa-react-app my-dashboard
+
+# Navigate to the project
+cd my-dashboard
+
+# Install dependencies (if not auto-installed)
+npm install
+
+# Start development server
+npm run dev
+```
+
+## Template Included
+
+### BlueCopa Basic Template
+
+A foundational template that provides:
+
+- **Modern React Setup**: React 18 with TypeScript and Vite
+- **BlueCopa Components**: Pre-configured @bluecopa/react component library
+- **UI Foundation**: Complete shadcn/ui component suite with Radix UI primitives
+- **Styling System**: Tailwind CSS with BlueCopa design tokens
+- **Development Setup**: ESLint, TypeScript configuration, and build optimization
+- **Environment Configuration**: Ready-to-use environment variable setup
+
+#### Key Dependencies Included
+
+```typescript
+// Core BlueCopa and React ecosystem
+"@bluecopa/react": "^0.1.3"
+"react": "^18.2.0"
+"typescript": "^5.0.2"
+
+// UI and Styling
+"@radix-ui/*": "Latest versions"
+"tailwindcss": "^3.3.0"
+"lucide-react": "^0.263.1"
+
+// Development and Build
+"vite": "^4.4.5"
+"@vitejs/plugin-react": "^4.0.3"
+```
+
+## Project Structure
+
+The generated project follows a clean, scalable structure:
+
+```text
+my-bluecopa-app/
+├── src/
+│   ├── components/
+│   │   └── ui/              # shadcn/ui components
+│   ├── lib/                 # Utilities and helpers
+│   ├── App.tsx              # Main application component
+│   ├── main.tsx             # Application entry point
+│   ├── index.css            # Global styles and Tailwind imports
+│   └── vite-env.d.ts        # Vite type declarations
+├── public/                  # Static assets
+├── .env.example             # Environment variables template
+├── package.json             # Dependencies and scripts
+├── tailwind.config.js       # Tailwind CSS configuration
+├── tsconfig.json            # TypeScript configuration
+├── vite.config.ts           # Vite build configuration
+└── README.md                # Project documentation
+```
+
+## Getting Started with Development
+
+### Adding BlueCopa Components
+
+The template includes @bluecopa/react components. Start building by importing and using them:
+
+```typescript
+import { SomeBlueCopaComponent } from '@bluecopa/react';
+
+function MyComponent() {
+  return (
+    <div>
+      <SomeBlueCopaComponent />
+    </div>
+  );
+}
+```
+
+### Adding UI Components
+
+Use the included shadcn/ui components for consistent styling:
+
+```typescript
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+
+function Dashboard() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>My Dashboard</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Click me</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### Styling and Theming
+
+- Modify `tailwind.config.js` for custom design tokens
+- Update CSS variables in `src/index.css` for theme customization
+- All shadcn/ui components support dark/light mode automatically
+
+## Environment Configuration
+
+Copy the included `.env.example` to `.env` and configure as needed:
+
+```bash
+cp .env.example .env
+```
+
+## Available Scripts
+
+- `npm run dev` - Start development server with hot reload
+- `npm run build` - Build for production (TypeScript compilation + Vite build)
+- `npm run preview` - Preview production build locally
+- `npm run lint` - Run ESLint for code quality
+- `npm run type-check` - Run TypeScript type checking without emitting files
+
+## Technologies Used
+
+- **React 18** - Modern React with concurrent features
+- **TypeScript** - Full type safety and developer experience
+- **Vite** - Fast build tool and development server
+- **@bluecopa/react** - BlueCopa-specific React components
+- **shadcn/ui** - High-quality, accessible component library
+- **Radix UI** - Unstyled, accessible UI primitives
+- **Tailwind CSS** - Utility-first CSS framework
+- **Lucide React** - Beautiful, customizable icons

package/bin/create-bluecopa-react-app.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const ora = require('ora');
+const { execSync } = require('child_process');
+const validatePackageName = require('validate-npm-package-name');
+
+const program = new Command();
+
+program
+  .version('1.0.0')
+  .name('create-bluecopa-react-app')
+  .description('Create a new Bluecopa React application')
+  .argument('[project-name]', 'Name of the project')
+  .option('--typescript', 'Use TypeScript template', true)
+  .option('--no-typescript', 'Use JavaScript template')
+  .option('--skip-install', 'Skip package installation')
+  .action(async (projectName, options) => {
+    try {
+      await createApp(projectName, options);
+    } catch (error) {
+      console.error(chalk.red('Error creating app:'), error.message);
+      process.exit(1);
+    }
+  });
+
+async function createApp(projectName, options) {
+  let appName = projectName;
+
+  // If no project name provided, prompt for it
+  if (!appName) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'projectName',
+        message: 'What is your project name?',
+        validate: (input) => {
+          if (!input) return 'Project name is required';
+          const validation = validatePackageName(input);
+          if (!validation.validForNewPackages) {
+            return validation.errors?.[0] || validation.warnings?.[0] || 'Invalid package name';
+          }
+          return true;
+        }
+      }
+    ]);
+    appName = answers.projectName;
+  }
+
+  // Validate project name
+  const validation = validatePackageName(appName);
+  if (!validation.validForNewPackages) {
+    console.error(chalk.red('Invalid project name:'), validation.errors?.[0] || validation.warnings?.[0]);
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), appName);
+
+  // Check if directory already exists
+  if (fs.existsSync(targetDir)) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Directory ${appName} already exists. Overwrite?`,
+        default: false
+      }
+    ]);
+
+    if (!answers.overwrite) {
+      console.log(chalk.yellow('Operation cancelled.'));
+      return;
+    }
+
+    await fs.remove(targetDir);
+  }
+
+  console.log(chalk.blue(`Creating a new Bluecopa React app in ${chalk.green(targetDir)}`));
+  console.log();
+
+  // Create app
+  const spinner = ora('Creating project structure...').start();
+  
+  try {
+    await createProjectStructure(targetDir, appName, options);
+    spinner.succeed('Project structure created');
+
+    if (!options.skipInstall) {
+      spinner.start('Installing dependencies...');
+      await installDependencies(targetDir);
+      spinner.succeed('Dependencies installed');
+    }
+
+    spinner.succeed(chalk.green('Success! Created ' + appName + ' at ' + targetDir));
+    
+    console.log();
+    console.log('Inside that directory, you can run several commands:');
+    console.log();
+    console.log(chalk.cyan('  npm start'));
+    console.log('    Starts the development server.');
+    console.log();
+    console.log(chalk.cyan('  npm run build'));
+    console.log('    Bundles the app into static files for production.');
+    console.log();
+    console.log(chalk.cyan('  npm test'));
+    console.log('    Starts the test runner.');
+    console.log();
+    console.log('We suggest that you begin by typing:');
+    console.log();
+    console.log(chalk.cyan('  cd'), appName);
+    console.log(chalk.cyan('  npm start'));
+    console.log();
+    console.log('Happy coding with Bluecopa! 🚀');
+
+  } catch (error) {
+    spinner.fail('Failed to create project');
+    throw error;
+  }
+}
+
+async function createProjectStructure(targetDir, appName, options) {
+  const templateDir = path.join(__dirname, '../templates/basic');
+  
+  // Create base directory
+  await fs.ensureDir(targetDir);
+  
+  // Copy template files
+  await fs.copy(templateDir, targetDir);
+  
+  // Update package.json with project name
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  const packageJson = await fs.readJson(packageJsonPath);
+  packageJson.name = appName;
+  await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+  
+  // Update index.html title if it exists
+  const indexHtmlPath = path.join(targetDir, 'public/index.html');
+  if (await fs.pathExists(indexHtmlPath)) {
+    let indexHtml = await fs.readFile(indexHtmlPath, 'utf8');
+    indexHtml = indexHtml.replace(/{{APP_NAME}}/g, appName);
+    await fs.writeFile(indexHtmlPath, indexHtml);
+  }
+}
+
+async function installDependencies(targetDir) {
+  try {
+    // Change to target directory and install
+    process.chdir(targetDir);
+    
+    // Check if yarn is available, otherwise use npm
+    let packageManager = 'npm';
+    try {
+      execSync('yarn --version', { stdio: 'ignore' });
+      packageManager = 'yarn';
+    } catch {
+      // yarn not available, use npm
+    }
+    
+    const installCommand = packageManager === 'yarn' ? 'yarn install' : 'npm install';
+    execSync(installCommand, { stdio: 'inherit' });
+    
+  } catch (error) {
+    throw new Error('Failed to install dependencies: ' + error.message);
+  }
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "create-bluecopa-react-app",
+  "version": "1.0.0",
+  "description": "CLI tool to create bluecopa React applications",
+  "main": "./bin/create-bluecopa-react-app.js",
+  "bin": {
+    "create-bluecopa-react-app": "./bin/create-bluecopa-react-app.js"
+  },
+  "keywords": [
+    "bluecopa",
+    "react",
+    "cli",
+    "boilerplate",
+    "data-visualization",
+    "charts",
+    "tables"
+  ],
+  "scripts": {
+    "format": "prettier --ignore-path .gitignore --write --plugin-search-dir=. ."
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "chalk": "^4.1.2",
+    "inquirer": "^8.2.6",
+    "ora": "^5.4.1",
+    "validate-npm-package-name": "^5.0.0"
+  },
+  "devDependencies": {},
+  "author": "Bluecopa UI Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluecopa/blui.git",
+    "directory": "packages/boilerplate/react"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/basic/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/basic/.env.example

@@ -0,0 +1,10 @@
+# BlueCopa API Configuration
+REACT_APP_API_BASE_URL=https://api.bluecopa.com
+REACT_APP_API_KEY=your_api_key_here
+
+# Environment
+NODE_ENV=development
+
+# Optional: Analytics and Monitoring
+REACT_APP_SENTRY_DSN=your_sentry_dsn
+REACT_APP_ANALYTICS_ID=your_analytics_id

package/templates/basic/README.md

@@ -0,0 +1,213 @@
+# BlueCopa Dashboard Template
+
+A modern React dashboard template for BlueCopa applications built with TanStack Query, shadcn/ui, and Recharts.
+
+## Features
+
+- 🚀 **Modern Tech Stack**: React 18, TypeScript, Vite
+- 📊 **Data Fetching**: TanStack Query for server state management
+- 🎨 **UI Components**: shadcn/ui with Radix UI primitives
+- 📈 **Charts**: Recharts for beautiful data visualizations
+- 🎯 **Type Safety**: Full TypeScript support
+- 🔄 **Real-time Updates**: Automatic data refetching and caching
+- 📱 **Responsive Design**: Mobile-first responsive layout
+- 🌙 **Dark Mode**: Built-in dark mode support
+
+## Quick Start
+
+1. **Install dependencies**:
+   ```bash
+   npm install
+   # or
+   yarn install
+   # or
+   pnpm install
+   ```
+
+2. **Start the development server**:
+   ```bash
+   npm run dev
+   ```
+
+3. **Open your browser** and navigate to `http://localhost:5173`
+
+## Project Structure
+
+```
+src/
+├── components/          # Reusable UI components
+│   ├── ui/             # shadcn/ui components
+│   └── dashboard/      # Dashboard-specific components
+├── lib/                # Utilities and helpers
+├── pages/              # Page components
+├── services/           # API services and data fetching
+├── types/              # TypeScript type definitions
+├── App.tsx             # Main application component
+└── main.tsx            # Application entry point
+```
+
+## Components Overview
+
+### Dashboard Components
+
+- **MetricsOverview**: Key performance indicators and metrics cards
+- **TransactionCharts**: Interactive charts showing sales data, payment methods, and analytics
+- **TransactionTable**: Data table with transaction details and filters
+
+### Features Demonstrated
+
+1. **TanStack Query Integration**:
+   - Automatic caching and background updates
+   - Loading states and error handling
+   - Query invalidation and refetching
+
+2. **Data Visualization**:
+   - Bar charts for category sales and state analytics
+   - Pie charts for payment method distribution
+   - Line charts for trend analysis
+
+3. **Real Transaction Data**:
+   - Based on actual BlueCopa transaction dataset
+   - Proper data typing with TypeScript
+   - Mock API responses for development
+
+## API Integration
+
+The template includes a mock API service (`src/services/api.ts`) that demonstrates:
+
+- Dataset queries for transaction data
+- Metric queries for aggregated data
+- User authentication and organization data
+- Proper error handling and loading states
+
+### Replacing Mock Data
+
+To use real APIs, update the `BlueCOPAApi` service:
+
+```typescript
+// In src/services/api.ts
+export const BlueCOPAApi = {
+  getDataset: async (datasetId: string) => {
+    const response = await apiClient.get(`/datasets/${datasetId}`);
+    return response.data;
+  },
+  // ... other methods
+};
+```
+
+## Customization
+
+### Adding New Charts
+
+1. Create a new component in `src/components/dashboard/`
+2. Use Recharts components for visualization
+3. Add TanStack Query for data fetching
+4. Include proper TypeScript types
+
+### Extending the API
+
+1. Add new types to `src/types/index.ts`
+2. Extend the API service in `src/services/api.ts`
+3. Create corresponding UI components
+4. Add new routes if needed
+
+### Styling
+
+The template uses Tailwind CSS with shadcn/ui design system:
+
+- Modify `tailwind.config.js` for custom themes
+- Update CSS variables in `src/index.css` for color schemes
+- Use the `cn()` utility for conditional styling
+
+## Data Types
+
+The template includes comprehensive TypeScript types for BlueCopa data:
+
+```typescript
+interface TransactionRecord {
+  transaction_id: string;
+  transaction_day: string;
+  city: string;
+  category: string;
+  total_amount: number;
+  payment_method: string;
+  // ... other fields
+}
+```
+
+## Development
+
+### Available Scripts
+
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run lint` - Run ESLint
+- `npm run type-check` - Run TypeScript compiler
+
+### Environment Variables
+
+Create a `.env` file for configuration:
+
+```
+REACT_APP_API_BASE_URL=https://api.bluecopa.com
+REACT_APP_API_KEY=your_api_key
+```
+
+## Deployment
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+The built files will be in the `dist/` directory.
+
+### Deploy to Vercel
+
+```bash
+vercel --prod
+```
+
+### Deploy to Netlify
+
+```bash
+netlify deploy --prod --dir=dist
+```
+
+## Technologies Used
+
+- **React 18** - UI framework
+- **TypeScript** - Type safety
+- **Vite** - Build tool and dev server
+- **TanStack Query** - Server state management
+- **shadcn/ui** - UI component library
+- **Radix UI** - Headless UI primitives
+- **Recharts** - Chart library
+- **Tailwind CSS** - Utility-first CSS framework
+- **React Router** - Client-side routing
+- **Axios** - HTTP client
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This template is part of the BlueCopa platform and follows the project's licensing terms.
+
+## Support
+
+For questions and support:
+- Check the [BlueCopa documentation](https://docs.bluecopa.com)
+- Open an issue in the repository
+- Contact the BlueCopa team
+
+---
+
+Built with ❤️ by the BlueCopa team

package/templates/basic/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>BlueCopa Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>