create-bluecopa-react-app 1.0.5 → 1.0.7

package/templates/latest/Agent.md

@@ -0,0 +1,254 @@
+# AI Agent Guide for BlueCopa React shadcn/ui Template
+
+This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this BlueCopa React application template.
+
+## 🏗️ Project Architecture Overview
+
+### Core Stack
+- **React 18** with TypeScript
+- **React Router v7** with SSR support
+- **shadcn/ui** components built on Radix UI
+- **Tailwind CSS v4** with CSS variables
+- **Vite 6** for build tooling
+- **TanStack Query** (via @bluecopa/react)
+
+### Key Directories
+```
+app/
+├── components/          # Reusable UI components
+│   ├── ui/             # shadcn/ui components
+│   ├── app-sidebar.tsx # Main navigation
+│   ├── data-table.tsx  # TanStack Table wrapper
+│   └── chart-*.tsx     # Recharts components
+├── hooks/              # Custom React hooks
+├── lib/                # Utilities and configurations
+├── routes/             # React Router pages
+└── dashboard/          # Sample data and components
+```
+
+## 🎨 Component Patterns
+
+### shadcn/ui Components
+All UI components follow shadcn/ui patterns:
+- Located in `app/components/ui/`
+- Built on Radix UI primitives
+- Styled with Tailwind CSS
+- Use `cn()` utility for class merging
+- Support dark mode via CSS variables
+
+### Custom Components
+- Use TypeScript interfaces for props
+- Follow React best practices (hooks, memo, etc.)
+- Implement proper accessibility
+- Use semantic HTML elements
+
+### Example Component Structure
+```tsx
+import { cn } from "~/lib/utils"
+
+interface ComponentProps {
+  className?: string
+  children: React.ReactNode
+}
+
+export function Component({ className, children }: ComponentProps) {
+  return (
+    <div className={cn("base-styles", className)}>
+      {children}
+    </div>
+  )
+}
+```
+
+## 🔧 Development Patterns
+
+### State Management
+- Use React hooks (useState, useReducer, useContext)
+- TanStack Query for server state
+- Local state for UI interactions
+- Avoid prop drilling with context
+
+### Data Fetching
+- Use `@bluecopa/react` hooks for API calls
+- Implement loading and error states
+- Use TanStack Query for caching
+- Handle optimistic updates
+
+### Styling Guidelines
+- Use Tailwind CSS classes
+- Leverage CSS variables for theming
+- Follow mobile-first responsive design
+- Use `cn()` utility for conditional classes
+
+## 📊 Data Visualization
+
+### Charts (Recharts)
+- Interactive charts with hover states
+- Responsive design
+- Customizable colors via CSS variables
+- Accessible with proper ARIA labels
+
+### Tables (TanStack Table)
+- Sortable columns
+- Filtering capabilities
+- Pagination support
+- Row selection
+- Custom cell renderers
+
+## 🎯 Common Tasks & Solutions
+
+### Adding New Pages
+1. Create route file in `app/routes/`
+2. Export default component
+3. Add navigation link in sidebar
+4. Implement proper TypeScript types
+
+### Adding New Components
+1. Create component file in appropriate directory
+2. Define TypeScript interface for props
+3. Use shadcn/ui components as base
+4. Implement responsive design
+5. Add proper accessibility attributes
+
+### Working with Forms
+1. Use shadcn/ui form components
+2. Implement validation with Zod
+3. Handle form state with React hooks
+4. Show loading and error states
+5. Use proper form semantics
+
+### API Integration
+1. Use `@bluecopa/react` hooks
+2. Handle loading states
+3. Implement error boundaries
+4. Use TanStack Query for caching
+5. Add optimistic updates where appropriate
+
+## 🚀 Performance Optimization
+
+### Code Splitting
+- Use React.lazy() for route-based splitting
+- Implement proper loading states
+- Avoid unnecessary re-renders
+
+### Bundle Optimization
+- Use Vite's built-in optimizations
+- Implement proper tree shaking
+- Optimize images and assets
+
+### Runtime Performance
+- Use React.memo() for expensive components
+- Implement proper key props
+- Avoid inline object/function creation
+
+## 🧪 Testing Strategies
+
+### Component Testing
+- Test component behavior, not implementation
+- Use React Testing Library
+- Mock external dependencies
+- Test accessibility features
+
+### Integration Testing
+- Test user workflows
+- Mock API responses
+- Test error scenarios
+- Verify responsive behavior
+
+## 🔒 Security Considerations
+
+### Data Handling
+- Sanitize user inputs
+- Validate data on client and server
+- Use proper TypeScript types
+- Implement proper error handling
+
+## 📱 Responsive Design
+
+### Breakpoints
+- Mobile-first approach
+- Use Tailwind's responsive prefixes
+- Test on multiple devices
+- Implement touch-friendly interactions
+
+### Layout Patterns
+- Use CSS Grid and Flexbox
+- Implement proper spacing
+- Handle overflow scenarios
+- Ensure proper scrolling
+
+## 🌙 Dark Mode Implementation
+
+### Theme System
+- Use next-themes for theme switching
+- Implement CSS variables for colors
+- Test both light and dark modes
+- Ensure proper contrast ratios
+
+### Component Theming
+- Use semantic color tokens
+- Implement proper hover states
+- Test theme transitions
+- Ensure accessibility compliance
+
+## 🐛 Debugging Tips
+
+### Common Issues
+- Check TypeScript errors first
+- Verify component imports
+- Check Tailwind class names
+- Validate API responses
+
+### Development Tools
+- Use React DevTools
+- Leverage Vite's HMR
+- Check browser console
+- Use TypeScript strict mode
+
+## 📚 Useful Resources
+
+### Documentation
+- [React Router v7 Docs](https://reactrouter.com/)
+- [shadcn/ui Components](https://ui.shadcn.com/)
+- [Tailwind CSS v4](https://tailwindcss.com/)
+- [TanStack Table](https://tanstack.com/table)
+- [Recharts](https://recharts.org/)
+
+### BlueCopa Specific
+- [@bluecopa/react Package](packages/react:1)
+- BlueCopa Design System
+- API Integration Patterns
+
+## 🎯 Best Practices Summary
+
+1. **Always use TypeScript** - Define proper interfaces and types
+2. **Follow shadcn/ui patterns** - Use established component structure
+3. **Implement accessibility** - Use semantic HTML and ARIA attributes
+4. **Optimize for performance** - Use proper React patterns and code splitting
+5. **Test thoroughly** - Write tests for components and user workflows
+6. **Handle errors gracefully** - Implement proper error boundaries and fallbacks
+7. **Follow responsive design** - Mobile-first approach with proper breakpoints
+8. **Use proper state management** - Choose appropriate patterns for different data types
+9. **Implement proper loading states** - Show feedback during async operations
+10. **Follow security best practices** - Validate inputs and secure API calls
+
+## 🔄 Common Workflows
+
+### Adding a New Feature
+1. Create feature branch
+2. Implement components with TypeScript
+3. Add proper styling with Tailwind
+4. Implement responsive design
+5. Add tests
+6. Update documentation
+7. Test in both light and dark modes
+
+### Debugging Issues
+1. Check browser console for errors
+2. Verify TypeScript compilation
+3. Test component isolation
+4. Check API responses
+5. Verify responsive behavior
+6. Test accessibility features
+
+This guide should help AI assistants and developers work effectively with this BlueCopa React template, ensuring consistent patterns and best practices are followed throughout development.

package/templates/latest/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:20-alpine AS development-dependencies-env
+COPY . /app
+WORKDIR /app
+RUN npm ci
+
+FROM node:20-alpine AS production-dependencies-env
+COPY ./package.json package-lock.json /app/
+WORKDIR /app
+RUN npm ci --omit=dev
+
+FROM node:20-alpine AS build-env
+COPY . /app/
+COPY --from=development-dependencies-env /app/node_modules /app/node_modules
+WORKDIR /app
+RUN npm run build
+
+FROM node:20-alpine
+COPY ./package.json package-lock.json /app/
+COPY --from=production-dependencies-env /app/node_modules /app/node_modules
+COPY --from=build-env /app/build /app/build
+WORKDIR /app
+CMD ["npm", "run", "start"]

package/templates/latest/README.md

@@ -1,263 +1,199 @@
-# BlueCopa React App Template
+# BlueCopa React App with shadcn/ui
 
-A production-ready React template with React Router for building modern BlueCopa dashboard applications with integrated React hooks, beautiful UI components, and comprehensive data visualization capabilities.
+A modern, production-ready template for building full-stack React applications using React Router v7 and shadcn/ui components.
 
-## 🎨 Design System
 
-This template now uses the latest Bluecopa design system with:
-- **Navy Blue Header**: Uses the official Bluecopa navy color (`#041e42`) for headers and navigation
-- **Modern Card Layout**: Clean, borderless cards with subtle shadows and consistent padding
-- **Consistent Spacing**: Improved spacing and layout following the latest app design system
-- **User Profile Integration**: Modern user dropdown with avatar, profile information, and logout
-- **Search & Notifications**: Built-in search bar and notification system with Radix UI
-- **Responsive Design**: Mobile-first approach with proper responsive breakpoints and device testing
+## Features
 
-## 🚀 Quick Start
+- 🚀 **React Router v7** - Latest React Router with server-side rendering
+- ⚡️ **Hot Module Replacement (HMR)** - Lightning-fast development experience
+- 📦 **Asset bundling and optimization** - Vite-powered build system
+- 🔄 **Data loading and mutations** - Built-in data fetching patterns
+- 🔒 **TypeScript by default** - Full type safety and developer experience
+- 🎨 **shadcn/ui Components** - Beautiful, accessible UI components built on Radix UI
+- 🎉 **TailwindCSS v4** - Latest Tailwind with CSS variables and modern features
+- 📊 **Data Visualization** - Recharts integration for charts and analytics
+- 🗂️ **Data Tables** - TanStack Table with sorting, filtering, and pagination
+- 🎯 **Drag & Drop** - DND Kit integration for interactive interfaces
+- 📱 **Responsive Design** - Mobile-first approach with sidebar navigation
+- 🌙 **Dark Mode** - Built-in theme switching with next-themes
+- 🔗 **BlueCopa API integration** - Pre-configured with `@bluecopa/react` hooks
+- 📖 [React Router docs](https://reactrouter.com/)
+- 🎨 [shadcn/ui docs](https://ui.shadcn.com/)
 
-> **Note**: This template is typically generated using the `create-bluecopa-react-app` CLI tool. If you're using this template directly, follow the manual setup instructions below.
+## Getting Started
 
-### Using the CLI Tool (Recommended)
+### Installation
+
+Install the dependencies:
 
 ```bash
-# Install globally
-npm install -g create-bluecopa-react-app
+npm install
+# or
+pnpm install
+```
 
-# Create new app
-create-bluecopa-react-app my-dashboard
+**Note:** The application includes TanStack Query integration through the `@bluecopa/react` package for data fetching and caching, along with shadcn/ui components for a modern UI experience.
 
-# Or use npx
-npx create-bluecopa-react-app my-dashboard
-```
+## Quick Start
 
-### Manual Setup
-
-### Prerequisites
-- Node.js 18+ 
-- npm or pnpm
-- Access to Bluecopa workspace
-
-
-2. **Install dependencies**:
-   ```bash
-   # Recommended: Use pnpm (consistent with monorepo)
-   pnpm install
-   
-   # Alternative: Use npm
-   npm install
-   ```
-
-3. **Set up environment variables**:
-   ```bash
-   # Automated setup (recommended)
-   ./setup.sh
-   
-   # Manual setup
-   cp .env.example .env.local
-   # Edit .env.local with your Bluecopa credentials from dashboard -> Settings -> API Tokens
-   ```
-
-4. **Start development server**:
-   ```bash
-   npm run dev
-   ```
-
-5. **Open your browser**: Navigate to [http://localhost:3000](http://localhost:3000)
-
-## ✨ Features
-
-### 🎯 Core Capabilities
-- **React 18** with TypeScript
-- **React Router v6** for client-side routing
-- **Vite** for fast development and building
-- **@bluecopa/react** - Complete hook library for Bluecopa APIs
-- **TailwindCSS** - Utility-first CSS framework
-- **Radix UI** - Accessible component primitives
-- **Lucide React** - Beautiful icon library
-- **Recharts** - Composable charting library
+This template is designed to work both as a standalone application and as a microfrontend within the BlueCopa ecosystem. It includes:
 
-### 🏗️ Architecture
-- **Component-based** architecture with reusable UI components
-- **Custom hooks** for API integration and data management
-- **TypeScript** for type safety and better developer experience
-- **Responsive design** that works on all devices
-- **Modern React patterns** with functional components and hooks
-
-### 📊 Bluecopa Integration
-- **Pre-configured hooks** for user data, metrics, and datasets
-- **Real-time data** fetching with TanStack Query
-- **Error handling** and loading states
-- **Authentication** integration
-- **Type-safe** API responses
-
-### 🎨 UI Components
-- **Card layouts** for dashboard sections
-- **Data tables** for displaying datasets
-- **Charts and graphs** for data visualization
-- **Form components** with validation
-- **Navigation** components with routing
-- **Responsive grid** layouts
-
-## 📁 Project Structure
+- **Single-spa integration** for microfrontend architecture
+- **Module federation** support for dynamic imports
+- **BlueCopa API integration** with pre-configured hooks
+- **Production-ready** Docker configuration
 
+### Development
+
+Start the development server with HMR:
+
+```bash
+npm run dev
 ```
-src/
-├── components/          # Reusable components
-│   ├── layout/         # Layout components (dashboard-header.tsx, dashboard-layout.tsx, sidebar.tsx)
-│   ├── page/           # Page-specific components (dashboard.tsx)
-│   ├── tables/         # Table components (data-grid.tsx)
-│   └── ui/             # Base UI components (alert.tsx, avatar.tsx, badge.tsx, bluecopa-logo.tsx, button.tsx, card.tsx, dropdown-menu.tsx, input.tsx, label.tsx, select.tsx)
-├── hooks/              # Custom React hooks
-│   └── use-api.ts      # Bluecopa API hooks
-├── lib/                # Utility functions
-│   └── utils.ts        # Helper functions
-├── pages/              # Route components
-│   ├── Home.tsx        # Home page
-│   └── Dashboard.tsx   # Dashboard page
-├── providers/          # React context providers
-│   └── query-provider.tsx  # TanStack Query provider
-├── types/              # TypeScript type definitions
-│   └── api.ts          # API type definitions
-├── App.tsx             # Main app component with routing
-├── index.css           # Global styles
-├── main.tsx            # Application entry point
-├── single-spa.tsx      # Single-spa configuration
-└── vite-env.d.ts       # Vite environment types
-```
 
-## 🔧 Configuration
+Your application will be available at `http://localhost:8080`.
+
+## UI Components
+
+This template includes a comprehensive set of shadcn/ui components:
+
+### Layout Components
+- **Sidebar** - Collapsible navigation sidebar with mobile support
+- **Sheet** - Slide-out panels for mobile navigation
+- **Drawer** - Bottom drawer for mobile interactions
+
+### Form Components
+- **Button** - Multiple variants and sizes
+- **Input** - Text input with validation states
+- **Select** - Dropdown selection with search
+- **Checkbox** - Checkbox with indeterminate state
+- **Label** - Accessible form labels
+
+### Data Display
+- **Table** - Sortable, filterable data tables with TanStack Table
+- **Card** - Content containers with header, content, and footer
+- **Badge** - Status indicators and labels
+- **Avatar** - User profile images with fallbacks
+- **Skeleton** - Loading placeholders
+
+### Navigation
+- **Tabs** - Tabbed content organization
+- **Breadcrumb** - Navigation breadcrumbs
+- **Dropdown Menu** - Context menus and actions
+- **Tooltip** - Hover information
+
+### Feedback
+- **Sonner** - Toast notifications
+- **Separator** - Visual content dividers
+
+### Charts
+- **Interactive Charts** - Recharts integration with hover states
+- **Area Charts** - Time series data visualization
+
+### Bluecopa API Configuration
+
+This application integrates with the Bluecopa API using the `@bluecopa/react` package. To use the `useUser` hook for displaying logged-in user information, set up the following environment variables:
 
-### Environment Variables
-Create a `.env.local` file in the root directory:
+Create a `.env` file in the root directory:
 
 ```bash
 # Bluecopa API Configuration
-VITE_BLUECOPA_API_TOKEN=your-bluecopa-api-token
-VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
-VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
+VITE_BLUECOPA_WORKSPACE_ID=your_workspace_id_here
+VITE_BLUECOPA_API_TOKEN=your_base64_encoded_token_here
 ```
 
-### Getting Your Credentials
-1. Log in to your Bluecopa workspace
-2. Navigate to Settings > API Keys
-3. Generate or copy your API token
-4. Note your workspace ID from the URL or settings
-
-## 🛠️ 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
-
-### Adding New Routes
-Add new routes in `src/App.tsx`:
-
-```tsx
-import { Routes, Route } from 'react-router-dom'
-import NewPage from '@/pages/NewPage'
-
-export default function App() {
-  return (
-    <QueryProvider>
-      <Routes>
-        <Route path="/" element={<Home />} />
-        <Route path="/dashboard" element={<Dashboard />} />
-        <Route path="/new-page" element={<NewPage />} />
-      </Routes>
-    </QueryProvider>
-  )
-}
+**Note:** `VITE_BLUECOPA_API_TOKEN` should be a base64-encoded JSON string containing an `accessToken` field, for example:
+```json
+{"accessToken": "your_access_token_here"}
 ```
+encoded as base64.
 
-### Adding Navigation Links
-Update the navigation in `src/components/layout/navbar.tsx`:
+If the API errors out or is not configured, the application will show "Set Environment" as the user name with email "setenv@email.com" as a fallback.
 
-```tsx
-const navigation = [
-  { name: 'Home', href: '/', icon: Home },
-  { name: 'Dashboard Overview', href: '/dashboard', icon: LayoutDashboard },
-  { name: 'New Page', href: '/new-page', icon: Settings },
-]
+## Building for Production
+
+Create a production build:
+
+```bash
+npm run build
 ```
 
-## 📚 API Integration
+## Deployment
 
-This template includes pre-configured hooks for common Bluecopa API operations:
+### Docker Deployment
 
-```tsx
-import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api'
+To build and run using Docker:
 
-function MyComponent() {
-  const { data: userData, isLoading, error } = useUserData()
-  const { data: metrics } = useMetricDataDemo()
-  const { data: datasets } = useDatasetDataDemo()
-  
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
-  
-  return <div>Welcome, {userData?.user?.firstName}!</div>
-}
+```bash
+docker build -t my-app .
+
+# Run the container
+docker run -p 3000:3000 my-app
 ```
 
-## 🎨 Styling
-
-The template uses TailwindCSS for styling with a custom design system:
-
-- **Color palette**: Bluecopa brand colors
-- **Typography**: Inter font family
-- **Spacing**: Consistent spacing scale
-- **Components**: Pre-built component styles
-
-### Customizing Colors
-Edit `tailwind.config.js` to modify the color scheme:
-
-```js
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        bluecopa: {
-          50: '#eff6ff',
-          // ... other shades
-          900: '#1e3a8a',
-        },
-      },
-    },
-  },
-}
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### DIY Deployment
+
+If you're familiar with deploying Node applications, the built-in app server is production-ready.
+
+Make sure to deploy the output of `npm run build`
+
+```
+├── package.json
+├── package-lock.json (or pnpm-lock.yaml, or bun.lockb)
+├── build/
+│   ├── client/    # Static assets
+│   └── server/    # Server-side code
 ```
 
-## 🚀 Deployment & Production
+## Adding More Components
+
+This template uses shadcn/ui CLI for adding new components. To add additional components:
 
-### Build for Production
 ```bash
-npm run build
+# Install shadcn/ui CLI globally
+npm install -g shadcn-ui@latest
+
+# Add components
+npx shadcn-ui@latest add [component-name]
+
+# Examples
+npx shadcn-ui@latest add dialog
+npx shadcn-ui@latest add alert
+npx shadcn-ui@latest add toast
 ```
 
-The production-ready files will be output to the `dist/` directory with optimized bundling and minification.
+## Styling
 
-### Production Best Practices
-- Validate environment variables before building
-- Test workflow triggers in staging environment
-- Monitor bundle size with `npm run build --report`
-- Use version control for deployment artifacts
+This template comes with [Tailwind CSS v4](https://tailwindcss.com/) configured with:
+- CSS variables for theming
+- Dark mode support with next-themes
+- shadcn/ui design system
+- Custom BlueCopa color palette
+- Responsive design utilities
 
-### Deploy to Vercel
-1. Push your code to GitHub
-2. Connect your repository to Vercel
-3. Set environment variables in Vercel dashboard
-4. Deploy
+## Key Technologies
 
-### Deploy to Netlify
-1. Build the project locally
-2. Upload the `dist/` folder to Netlify
-3. Set environment variables in Netlify dashboard
+- **React 18** - Latest React with concurrent features
+- **React Router v7** - Modern routing with SSR support
+- **shadcn/ui** - Accessible component library built on Radix UI
+- **Tailwind CSS v4** - Utility-first CSS framework
+- **TanStack Table** - Headless table library for React
+- **Recharts** - Composable charting library
+- **DND Kit** - Drag and drop toolkit
+- **Lucide React** - Beautiful icon library
+- **TypeScript** - Type safety and developer experience
 
-## 🔒 Environment Security
+---
 
-- Never commit `.env.local` files
-- Use environment variables for all sensitive data
-- Rotate API tokens regularly
-- Use different tokens for development and production
+Built with ❤️ using React Router v7 and shadcn/ui.