create-bluecopa-react-app 1.0.2 → 1.0.4

package/README.md

@@ -1,274 +1,132 @@
-# Create BlueCopa React App
+# create-bluecopa-react-app [![npm version](https://img.shields.io/npm/v/create-bluecopa-react-app)](https://www.npmjs.com/package/create-bluecopa-react-app) [![License](https://img.shields.io/npm/l/create-bluecopa-react-app)](LICENSE)
 
-A CLI tool to bootstrap modern React applications for BlueCopa with built-in UI components, data visualization capabilities, and development best practices.
+## A CLI Tool for BlueCopa React Applications
 
-## Features
+A command-line interface for bootstrapping modern React applications with BlueCopa integration, featuring opinionated best practices and pre-configured tooling.
 
-- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v6, Vite
-- 📊 **Data Visualization**: Recharts integration for charts and analytics
-- 🎨 **UI Components**: Radix UI primitives with custom styling
-- 📡 **BlueCopa React Components**: Pre-configured @bluecopa/react package with hooks
-- 🎯 **Type Safety**: Full TypeScript support
-- 📱 **Responsive Design**: Tailwind CSS with mobile-first approach and BlueCopa design system
-- 🛠️ **Development Tools**: ESLint, TypeScript checking, and Vite fast build system
-- ⚡ **Fast Development**: Hot module replacement with Vite
-- 🔄 **Client-side Routing**: React Router v6 for SPA navigation
-
-## Quick Start
-
-```bash
-# Install the CLI tool globally
-npm install -g create-bluecopa-react-app
+## Table of Contents
 
-# Create a new BlueCopa React app
-create-bluecopa-react-app my-dashboard
+- [Version](#version)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Features](#features)
+- [Usage](#usage)
+- [API Documentation](#api-documentation)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
-# Or use npx (no global installation needed)
-npx create-bluecopa-react-app my-dashboard
+## Version
 
-# Navigate to the project
-cd my-dashboard
+Current version: 0.1.0
 
-# Install dependencies (if not auto-installed)
-npm install
+## Installation
 
-# Start development server
-npm run dev
+```bash
+npm install -g create-bluecopa-react-app
+# or
+pnpm add -g create-bluecopa-react-app
 ```
 
-## Template Included
+## Requirements
 
-### BlueCopa React Router Template
+- Node.js >= 18.0.0
+- npm >= 9.0.0 or pnpm >= 8.0.0
 
-A foundational template that provides:
+## Configuration
 
-- **Modern React Setup**: React 18 with TypeScript, React Router v6, and Vite
-- **BlueCopa Components**: Pre-configured @bluecopa/react component library with hooks
-- **UI Foundation**: Radix UI primitives with custom styling system
-- **Data Visualization**: Recharts for charts and analytics
-- **Styling System**: Tailwind CSS with BlueCopa design tokens and navy theme
-- **Development Setup**: ESLint, TypeScript configuration, and Vite optimization
-- **Environment Configuration**: Ready-to-use environment variable setup
-- **Client-side Routing**: React Router v6 for smooth SPA navigation
+The CLI uses environment variables for configuration:
 
-#### Key Dependencies Included
+```bash
+# Optional configuration
+export BLUECOPA_BOILERPLATE_REGISTRY=https://registry.npmjs.org
+```
+
+## Features
 
-```typescript
-// Core BlueCopa and React ecosystem
-"@bluecopa/react": "^0.1.3"
-"react": "^18.3.0"
-"react-dom": "^18.3.0"
-"react-router-dom": "^6.26.0"
-"typescript": "^5.6.0"
+- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v6, Vite 7
+- 🌐 **Microfrontend Support**: Single-spa compatible with module federation
+- 📊 **Data Visualization**: Recharts integration for charts and analytics
+- 🎨 **UI Components**: Radix UI primitives with custom styling
+- 📡 **BlueCopa React Components**: Pre-configured [`@bluecopa/react`](packages/react:1) package with hooks (includes TanStack Query integration)
+- 🎯 **Type Safety**: Full TypeScript support
+- 📱 **Responsive Design**: Tailwind CSS with mobile-first approach and BlueCopa design system
+- 🛠️ **Development Tools**: ESLint, TypeScript checking, and Vite fast build system
+- ⚡ **Fast Development**: Hot module replacement with Vite
+- 🔄 **Client-side Routing**: React Router v6 for SPA navigation
 
-// UI and Styling
-"@radix-ui/*": "Latest versions"
-"tailwindcss": "^3.4.17"
-"lucide-react": "^0.445.0"
+## Usage
 
-// Data Visualization
-"recharts": "^2.12.0"
+### Creating a New Application
 
-// Development and Build
-"vite": "^5.4.20"
-"eslint": "^8.57.0"
-"@vitejs/plugin-react": "^4.3.0"
-```
+```bash
+# Create new app
+create-bluecopa-react-app my-dashboard
 
-## Project Structure
-
-The generated project follows a clean, scalable structure:
-
-```text
-my-bluecopa-app/
-├── src/
-│   ├── components/          # Reusable UI components
-│   │   ├── ui/             # Base UI components (buttons, cards, etc.)
-│   │   └── navbar.tsx      # Navigation component
-│   ├── hooks/              # Custom React hooks
-│   │   └── use-api.ts      # Bluecopa API hooks
-│   ├── lib/                # Utilities and helpers
-│   │   └── utils.ts        # Helper functions and utilities
-│   ├── pages/              # Route components
-│   │   ├── Home.tsx        # Home page component
-│   │   └── Dashboard.tsx   # Dashboard page component
-│   ├── providers/          # React context providers
-│   │   └── query-provider.tsx  # TanStack Query provider
-│   ├── types/              # TypeScript type definitions
-│   ├── App.tsx             # Main app component with routing
-│   ├── main.tsx            # Application entry point
-│   └── index.css           # Global styles and Tailwind imports
-├── public/                 # Static assets
-├── .env.example            # Environment variables template
-├── package.json            # Dependencies and scripts
-├── vite.config.ts          # Vite configuration
-├── tailwind.config.js      # Tailwind CSS configuration
-├── tsconfig.json           # TypeScript configuration
-├── postcss.config.js       # PostCSS configuration
-└── README.md               # Project documentation
+# Or use npx
+npx create-bluecopa-react-app my-dashboard
 ```
 
-## Getting Started with Development
+### CLI Options
 
-### Adding BlueCopa Components and Hooks
+| Option | Description |
+|--------|-------------|
+| `--skip-install` | Skip dependency installation |
+| `--template` | Specify template version (default: latest) |
+| `--help` | Show help information |
 
-The template includes @bluecopa/react components and hooks. Start building by importing and using them:
+## API Documentation
 
-```typescript
-import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api';
+### `create-bluecopa-react-app [project-name] [options]`
 
-function MyComponent() {
-  const { data: userData, isLoading, error } = useUserData();
-  const { data: metrics } = useMetricDataDemo();
-  
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  
-  return (
-    <div>
-      <h1>Welcome, {userData?.user?.firstName}!</h1>
-    </div>
-  );
-}
-```
+Creates a new BlueCopa React application.
 
-### Adding Routes
-
-Add new routes in `src/App.tsx`:
-
-```typescript
-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>
-  );
-}
-```
+**Parameters:**
+- `project-name`: Name of the new project directory
+- `options`: CLI options (see above)
 
-### Adding UI Components
-
-Use the included Radix UI components with Tailwind 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>
-  );
-}
-```
-
-### Adding Charts and Data Visualization
-
-Use Recharts for data visualization:
-
-```typescript
-import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
-
-const data = [
-  { name: 'Jan', value: 400 },
-  { name: 'Feb', value: 300 },
-  { name: 'Mar', value: 600 },
-];
-
-function ChartComponent() {
-  return (
-    <ResponsiveContainer width="100%" height={300}>
-      <LineChart data={data}>
-        <CartesianGrid strokeDasharray="3 3" />
-        <XAxis dataKey="name" />
-        <YAxis />
-        <Tooltip />
-        <Line type="monotone" dataKey="value" stroke="#8884d8" />
-      </LineChart>
-    </ResponsiveContainer>
-  );
-}
-```
+**Returns:**
+- Creates project structure
+- Installs dependencies
+- Configures environment
 
-### Environment Configuration
+## Examples
 
-Create a `.env.local` file from the example:
+### Basic Usage
 
 ```bash
-cp .env.example .env.local
-# Edit .env.local with your Bluecopa credentials from dashboard → Settings → API Tokens
+create-bluecopa-react-app my-dashboard
 ```
 
-Required environment variables:
+### Skipping Dependency Installation
+
 ```bash
-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
+create-bluecopa-react-app my-dashboard --skip-install
 ```
 
-## Available Scripts
+## Development
+
+### Available Scripts
 
 - `npm run dev` - Start Vite development server with hot reload
 - `npm run build` - Build for production (TypeScript + Vite optimization)
+- `npm run start` - Start production build locally
 - `npm run preview` - Preview production build locally
 - `npm run lint` - Run ESLint for code quality
+- `npm run lint:fix` - Fix linting issues
 - `npm run type-check` - Run TypeScript type checking without emitting files
+- `npm run clean` - Clean build artifacts and dependencies
 
-## Technologies Used
+### Technologies Used
 
 - **React 18** - Modern React with concurrent features
 - **React Router v6** - Declarative routing for React SPAs
 - **Vite** - Fast build tool and development server
 - **TypeScript** - Full type safety and developer experience
-- **@bluecopa/react** - BlueCopa-specific React components and hooks
-- **TanStack Query** - Powerful data synchronization for React
+- **[`@bluecopa/react`](packages/react:1)** - BlueCopa-specific React components and hooks
 - **Radix UI** - Unstyled, accessible UI primitives
 - **Recharts** - Composable charting library for React
 - **Tailwind CSS** - Utility-first CSS framework with BlueCopa design system
 - **Lucide React** - Beautiful, customizable icons
-
-## CLI Usage
-
-The CLI will prompt you for project details and automatically:
-
-- Create the project structure
-- Copy template files
-- Update package.json with your project name
-- Install dependencies (unless `--skip-install` is used)
-- Provide next steps for development
-
-Example output:
-
-```bash
-✔ Creating project structure...
-✔ Dependencies installed
-✔ Success! Created my-dashboard at /path/to/my-dashboard
-
-Inside that directory, you can run several commands:
-
-  npm run dev
-    Starts the development server.
-
-  npm run build
-    Bundles the app into static files for production.
-
-We suggest that you begin by typing:
-
-  cd my-dashboard
-  npm run dev
-
-Happy coding with Bluecopa! 🚀
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "CLI tool to create bluecopa React applications",
   "main": "./bin/create-bluecopa-react-app.js",
   "bin": {
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/templates/latest/{Agent.md → AGENT.md}

@@ -12,21 +12,21 @@ This template is designed to work seamlessly with AI coding assistants for rapid
 - **Frontend**: React 18 + TypeScript + React Router v6
 - **Build Tool**: Vite (fast HMR and building)
 - **Styling**: TailwindCSS with BlueCopa design system
-- **UI Components**: Radix UI primitives
-- **Data Fetching**: TanStack Query with @bluecopa/react hooks
+- **UI Components**: Radix UI primitives (add via shadcn-ui for pre-styled components)
+- **Data Fetching**: TanStack Query with @bluecopa/core hooks
 - **Charts**: Recharts for data visualization
 - **Icons**: Lucide React
 
 ### Key Directories
 ```
 src/
-├── components/ui/       # Reusable UI components (Button, Card, etc.)
-├── components/         # Business logic components (Navbar, etc.)
-├── hooks/             # Custom React hooks and API integration
+├── components/ui/       # Reusable UI components (e.g., Button, Card via shadcn-ui; bluecopa-logo)
+├── components/         # Business logic components (Navbar, DashboardLayout, etc.)
+├── hooks/             # Custom React hooks (if needed; primarily use @bluecopa/core)
 ├── pages/             # Route components (Home, Dashboard)
-├── providers/         # React context providers
-├── lib/               # Utility functions and helpers
-└── types/             # TypeScript type definitions
+├── providers/         # React context providers (e.g., QueryProvider)
+├── lib/               # Utility functions and helpers (e.g., utils.ts with cn)
+└── types/             # TypeScript type definitions (e.g., for API responses)
 ```
 
 ## 🔧 Development Patterns
@@ -38,8 +38,13 @@ When asked to create a new page:
 1. **Create the page component** in `src/pages/NewPage.tsx`:
 ```tsx
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { useGetWorkflowInstanceStatusById } from '@bluecopa/core';
 
 export default function NewPage() {
+  const { data: workflowStatus, isLoading } = useGetWorkflowInstanceStatusById('workflowId');
+
+  if (isLoading) return <div>Loading...</div>;
+
   return (
     <div className="container mx-auto py-6">
       <Card>
@@ -48,6 +53,7 @@ export default function NewPage() {
         </CardHeader>
         <CardContent>
           {/* Page content */}
+          <p>Workflow status: {workflowStatus?.status}</p>
         </CardContent>
       </Card>
     </div>
@@ -63,8 +69,10 @@ import NewPage from '@/pages/NewPage';
 <Route path="/new-page" element={<NewPage />} />
 ```
 
-3. **Update navigation** in `src/components/navbar.tsx`:
+3. **Update navigation** in `src/components/page/navbar.tsx` (import icon from lucide-react):
 ```tsx
+import { Settings } from 'lucide-react';
+
 const navigation = [
   // ... existing routes
   { name: 'New Page', href: '/new-page', icon: Settings },
@@ -73,30 +81,36 @@ const navigation = [
 
 ### 2. Using BlueCopa API Hooks
 
-Always use the pre-configured hooks from `@/hooks/use-api.ts`:
+Install @bluecopa/core if not present: `npm install @bluecopa/core`
 
+Use the pre-configured hooks from `@bluecopa/core`:
 ```tsx
-import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api';
+import { useGetFileUrlByFileId, useGetTableById, useGetWorkflowInstanceStatusById } from '@bluecopa/core';
 
 function DataComponent() {
-  const { data: userData, isLoading, error } = useUserData();
-  const { data: metrics } = useMetricDataDemo();
+  const { data: fileUrlData, isLoading: fileUrlLoading } = useGetFileUrlByFileId('key', 'type', 'GET');
+  const { data: tableData } = useGetTableById('tableId');
+  const { data: workflowStatus } = useGetWorkflowInstanceStatusById('workflowId');
   
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (fileUrlLoading) return <div>Loading...</div>;
+  if (!fileUrlData) return <div>No data available</div>;
   
-  return <div>Data: {JSON.stringify(userData)}</div>;
+  return <div>Data: {JSON.stringify(fileUrlData)}</div>;
 }
 ```
 
+For custom hooks, create in `src/hooks/` and wrap TanStack Query.
+
 ### 3. UI Component Patterns
 
-Use the existing UI components from `src/components/ui/`:
+Add shadcn-ui components if needed: `npx shadcn-ui@latest add card button tabs`
 
+Use the existing UI components from `src/components/ui/`:
 ```tsx
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { cn } from '@/lib/utils';
 
 // Example usage
 <Card>
@@ -104,7 +118,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
     <CardTitle>Dashboard</CardTitle>
   </CardHeader>
   <CardContent>
-    <Tabs defaultValue="overview">
+    <Tabs defaultValue="overview" className={cn("w-full")}>
       <TabsList>
         <TabsTrigger value="overview">Overview</TabsTrigger>
         <TabsTrigger value="analytics">Analytics</TabsTrigger>
@@ -119,12 +133,19 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 
 ### 4. Chart Integration
 
-Use Recharts for data visualization:
+Install Recharts if not present: `npm install recharts`
 
+Use Recharts for data visualization:
 ```tsx
 import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 
-function ChartComponent({ data }: { data: any[] }) {
+interface ChartData {
+  name: string;
+  value: number;
+}
+
+function ChartComponent({ data }: { data: ChartData[] }) {
   return (
     <Card>
       <CardHeader>
@@ -177,27 +198,28 @@ function ChartComponent({ data }: { data: any[] }) {
 ## 🛠️ Common Tasks for Agents
 
 ### Adding a New Dashboard Card
-1. Create component in appropriate location
-2. Use Card component wrapper
-3. Include loading and error states
-4. Use BlueCopa hooks for data
+1. Create component in `src/components/` (e.g., NewCard.tsx)
+2. Use Card component wrapper from ui/
+3. Include loading and error states with TanStack Query
+4. Use @bluecopa/core hooks for data (e.g., useGetTableById)
 
 ### Creating Forms
-1. Use Radix UI form components
-2. Add TypeScript types for form data
-3. Include validation and error handling
+1. Use Radix UI form components (add via shadcn-ui: `npx shadcn-ui@latest add form`)
+2. Add TypeScript types for form data in `src/types/`
+3. Include validation with Zod and error handling
 4. Follow BlueCopa styling patterns
 
 ### Adding Data Tables
-1. Consider using AG Grid (@bluecopa/aggrid) for complex tables
+1. For complex tables, install and use AG Grid (@bluecopa/aggrid)
 2. For simple tables, use HTML table with Tailwind styling
 3. Include sorting, filtering, and pagination as needed
+4. Integrate with @bluecopa/core for data
 
 ### Implementing Search
-1. Add search state management
-2. Use debounced input for API calls
+1. Add search state management with React state or form libraries
+2. Use debounced input for API calls (e.g., via useGetTableById with query params)
 3. Show loading states during search
-4. Handle empty states gracefully
+4. Handle empty states gracefully with conditional rendering
 
 ## 🚨 Important Notes for Agents
 
@@ -209,18 +231,20 @@ const apiUrl = import.meta.env.VITE_BLUECOPA_API_URL;
 ```
 
 ### Imports
-Use path aliases consistently:
+Use path aliases consistently (configured in tsconfig.json):
 ```tsx
 import { Button } from '@/components/ui/button';
-import { useUserData } from '@/hooks/use-api';
+import { useGetTableById } from '@bluecopa/core';
 import { cn } from '@/lib/utils';
 ```
 
 ### TypeScript
 Always include proper TypeScript types:
 ```tsx
+import { FileUrlResponse, TableData, WorkflowStatus } from '@/types';
+
 interface ComponentProps {
-  data: UserData[];
+  data: TableData[];
   onSelect: (id: string) => void;
 }
 
@@ -232,19 +256,20 @@ function Component({ data, onSelect }: ComponentProps) {
 ### Error Handling
 Include proper error boundaries and loading states:
 ```tsx
-if (isLoading) return <div className="p-4">Loading...</div>;
+if (fileUrlLoading) return <div className="p-4">Loading...</div>;
 if (error) return <div className="p-4 text-red-600">Error: {error.message}</div>;
 if (!data) return <div className="p-4 text-gray-500">No data available</div>;
 ```
 
 ## 📚 Reference Links
-
 - [React Router Documentation](https://reactrouter.com)
 - [TailwindCSS Documentation](https://tailwindcss.com)
-- [Radix UI Documentation](https://radix-ui.com)
+- [Radix UI Documentation](https://www.radix-ui.com)
+- [shadcn/ui Documentation](https://ui.shadcn.com)
 - [Recharts Documentation](https://recharts.org)
-- [TanStack Query Documentation](https://tanstack.com/query)
-- [BlueCopa React Package](https://github.com/bluecopa/blui/packages/react)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [Lucide React Icons](https://lucide.dev)
+- [BlueCopa Core Package](https://www.npmjs.com/package/@bluecopa/core)
 
 ## 🔄 Development Workflow