create-bluecopa-react-app 1.0.11 → 1.0.13

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

@@ -42,7 +42,7 @@ Templates:
   latest    Basic React Router setup with essential components
 
 For more information, visit:
-  https://github.com/bluecopa/blui/tree/main/packages/boilerplate/react
+  https://github.com/bluecopa/blui/tree/dev/packages/boilerplate/react
 `)
   .action(async (projectName, options) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "CLI tool to create bluecopa React applications",
   "type": "module",
   "main": "./bin/create-bluecopa-react-app.js",

package/templates/latest/.dockerignore

@@ -1 +1,5 @@
-node_modules/
+node_modules/
+dist
+.git
+*.log
+.DS_Store

package/templates/latest/Agent.md

@@ -74,6 +74,627 @@ export function Component({ className, children }: ComponentProps) {
 - Use TanStack Query for caching
 - Handle optimistic updates
 
+# @bluecopa/react [![npm version](https://img.shields.io/npm/v/@bluecopa/react)](https://www.npmjs.com/package/@bluecopa/react) [![License](https://img.shields.io/npm/l/@bluecopa/react)](https://github.com/bluecopa/blui/blob/main/packages/react/LICENSE)
+
+## A Comprehensive React Query Integration for Bluecopa
+
+A React library providing opinionated custom hooks for TanStack React Query integration with Bluecopa core API. This package enables efficient data fetching, caching, and synchronization with the Bluecopa platform while maintaining type safety and developer experience.
+
+## Table of Contents
+
+- [AI Agent Guide for BlueCopa React shadcn/ui Template](#ai-agent-guide-for-bluecopa-react-shadcnui-template)
+  - [🏗️ Project Architecture Overview](#️-project-architecture-overview)
+    - [Core Stack](#core-stack)
+    - [Key Directories](#key-directories)
+  - [🎨 Component Patterns](#-component-patterns)
+    - [shadcn/ui Components](#shadcnui-components)
+    - [Custom Components](#custom-components)
+    - [Example Component Structure](#example-component-structure)
+  - [🔧 Development Patterns](#-development-patterns)
+    - [State Management](#state-management)
+    - [Data Fetching](#data-fetching)
+- [@bluecopa/react  ](#bluecopareact--)
+  - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+    - [Peer Dependencies](#peer-dependencies)
+  - [Usage](#usage)
+    - [Query Provider Setup](#query-provider-setup)
+    - [Boilerplate Integration](#boilerplate-integration)
+    - [Hook Examples](#hook-examples)
+      - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
+      - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
+  - [API Documentation](#api-documentation)
+    - [`useUser(options?)`](#useuseroptions)
+    - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
+    - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
+    - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
+    - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
+    - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
+    - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
+    - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
+    - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
+    - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
+    - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
+    - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
+    - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
+    - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
+    - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
+    - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
+    - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
+    - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
+    - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
+    - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
+  - [Configuration](#configuration)
+    - [Default Query Configuration](#default-query-configuration)
+    - [Customizable Parameters](#customizable-parameters)
+  - [Advanced Usage](#advanced-usage)
+    - [Error Handling](#error-handling)
+    - [Manual Refetching](#manual-refetching)
+  - [Re-exports](#re-exports)
+    - [Styling Guidelines](#styling-guidelines)
+  - [📊 Data Visualization](#-data-visualization)
+    - [Charts (Recharts)](#charts-recharts)
+    - [Tables (TanStack Table)](#tables-tanstack-table)
+  - [🎯 Common Tasks \& Solutions](#-common-tasks--solutions)
+    - [Adding New Pages](#adding-new-pages)
+    - [Adding New Components](#adding-new-components)
+    - [Working with Forms](#working-with-forms)
+    - [API Integration](#api-integration)
+  - [🚀 Performance Optimization](#-performance-optimization)
+    - [Code Splitting](#code-splitting)
+    - [Bundle Optimization](#bundle-optimization)
+    - [Runtime Performance](#runtime-performance)
+  - [🧪 Testing Strategies](#-testing-strategies)
+    - [Component Testing](#component-testing)
+    - [Integration Testing](#integration-testing)
+  - [🔒 Security Considerations](#-security-considerations)
+    - [Data Handling](#data-handling)
+  - [📱 Responsive Design](#-responsive-design)
+    - [Breakpoints](#breakpoints)
+    - [Layout Patterns](#layout-patterns)
+  - [🌙 Dark Mode Implementation](#-dark-mode-implementation)
+    - [Theme System](#theme-system)
+    - [Component Theming](#component-theming)
+  - [🐛 Debugging Tips](#-debugging-tips)
+    - [Common Issues](#common-issues)
+    - [Development Tools](#development-tools)
+  - [📚 Useful Resources](#-useful-resources)
+    - [Documentation](#documentation)
+    - [BlueCopa Specific](#bluecopa-specific)
+  - [🎯 Best Practices Summary](#-best-practices-summary)
+  - [🔄 Common Workflows](#-common-workflows)
+    - [Adding a New Feature](#adding-a-new-feature)
+    - [Debugging Issues](#debugging-issues)
+
+## Features
+
+- ✅ First-class TypeScript support with strict type definitions
+- 🔁 Seamless integration with TanStack React Query (v5+)
+- 🛡 Comprehensive error handling patterns
+- ⚙ Optimized default query configuration
+- 📦 Re-exports of core TanStack React Query utilities
+- 📊 Sample data preview capabilities
+- 🧩 Customizable query parameters (limit, caching, retries)
+
+## Installation
+
+```bash
+npm install @bluecopa/react
+# or with pnpm
+pnpm add @bluecopa/react
+```
+
+### Peer Dependencies
+
+This package requires the following in your application:
+
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+```
+
+## Usage
+
+### Query Provider Setup
+
+Wrap your application with the React Query provider:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+### Boilerplate Integration
+
+For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
+
+```tsx
+// src/providers/query-provider.tsx
+import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
+import { useEffect, useState } from "react";
+
+const { QueryClient, QueryClientProvider } = reactQuery;
+
+export default function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // 1 minute
+        refetchOnWindowFocus: false,
+      },
+    },
+  }));
+
+  useEffect(() => {
+    let copaUser: any = {};
+    try {
+      const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
+        ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
+        : "{}";
+      
+      copaUser = JSON.parse(copaToken);
+    } catch (error) {
+      console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
+    }
+
+    copaSetConfig({
+      apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
+      workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
+      accessToken: copaUser?.accessToken || "",
+    });
+  }, []);
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+**Required Environment Variables:**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
+| `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
+| `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
+
+**Example `.env` file:**
+```
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
+VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
+VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
+```
+
+Then wrap your application with this provider:
+
+```tsx
+import QueryProvider from './providers/query-provider';
+
+function App() {
+  return (
+    <QueryProvider>
+      <YourApp />
+    </QueryProvider>
+  );
+}
+```
+
+This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
+
+### Hook Examples
+
+#### `useUser` - Fetch authenticated user
+
+```tsx
+import { useUser } from '@bluecopa/react';
+
+function UserProfile() {
+  const { data, isLoading, error } = useUser({
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 2
+  });
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return <div>Welcome, {data?.name}!</div>;
+}
+```
+
+#### `useDataset` - Fetch dataset with query controls
+
+```tsx
+import { useDataset } from '@bluecopa/react';
+
+function DatasetViewer({ datasetId }) {
+  const { data, isLoading } = useDataset(datasetId, {
+    limit: 500,
+    staleTime: 10 * 60 * 1000 // 10 minutes
+  });
+  
+  if (isLoading) return <div>Loading dataset...</div>;
+  return <div>{data?.name} ({data?.records?.length} records)</div>;
+}
+```
+
+## API Documentation
+
+### `useUser(options?)`
+
+Fetches authenticated user details with query controls.
+
+**Parameters:**  
+- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
+
+**Returns:**  
+- `data`: User object or `undefined`
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useDataset(datasetId, options?)`
+
+Fetches dataset data by ID with configurable parameters.
+
+**Parameters:**  
+- `datasetId`: ID of the dataset to fetch
+- `options` (optional): Query options with:
+  - `limit`: Maximum records to fetch
+  - `staleTime`: Duration (ms) before data is considered stale
+
+**Returns:**  
+- `data`: Dataset object containing name and records
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useDatasetSample(datasetId, options?)`
+
+Fetches a representative sample of dataset data.
+
+**Parameters:**  
+- `datasetId`: ID of the dataset
+- `options` (optional): Query options with `enabled` flag
+
+**Returns:**  
+- `data`: Object containing sample data
+- `isLoading`: Boolean indicating loading state
+- `refetch`: Function to manually trigger refetch
+
+### `useMetric(metricId, options?)`
+
+Fetches metric data by ID.
+
+**Parameters:**  
+- `metricId`: ID of the metric
+- `options` (optional): Query options
+
+**Returns:**  
+- `data`: Metric object with name and value
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useInputTable(inputTableId, options?)`
+
+Fetches input table data with limit parameters.
+
+**Parameters:**  
+- `inputTableId`: ID of the input table
+- `options` (optional): Query options with `limitParams`:
+  - `limit`: Maximum rows to fetch
+  - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
+
+**Returns:**  
+- `data`: Input table object with rows
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetFileUrlByFileId(fileId, options?)`
+
+Fetches the URL for a file by its ID.
+
+**Parameters:**
+- `fileId`: ID of the file to fetch URL for
+- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
+
+**Returns:**
+- `data`: Object containing file URL
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetPublishedWorkbookById(workbookId, options?)`
+
+Fetches published workbook details by ID.
+
+**Parameters:**
+- `workbookId`: ID of the published workbook
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Published workbook object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetTableById(tableId, options?)`
+
+Fetches table metadata by ID.
+
+**Parameters:**
+- `tableId`: ID of the table
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Table metadata object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetWorkbooksByType(workbookType, options?)`
+
+Fetches workbooks filtered by type.
+
+**Parameters:**
+- `workbookType`: Type of workbooks to fetch
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Array of workbook objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetWorkflowInstanceStatusById(instanceId, options?)`
+
+Fetches workflow instance status by ID.
+
+**Parameters:**
+- `instanceId`: ID of the workflow instance
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow status object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetWorksheets(options?)`
+
+Fetches all available worksheets.
+
+**Parameters:**
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Array of worksheet objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useGetWorksheetsByType(worksheetType, options?)`
+
+Fetches worksheets filtered by type.
+
+**Parameters:**
+- `worksheetType`: Type of worksheets to fetch
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Array of worksheet objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useRunDefinition(definitionId, options?)`
+
+Executes a run definition.
+
+**Parameters:**
+- `definitionId`: ID of the run definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useRunPublishedDefinition(publishedDefinitionId, options?)`
+
+Executes a published run definition.
+
+**Parameters:**
+- `publishedDefinitionId`: ID of the published definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useRunSampleDefinition(sampleDefinitionId, options?)`
+
+Executes a sample run definition.
+
+**Parameters:**
+- `sampleDefinitionId`: ID of the sample definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Sample execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useTriggerHttpWorkflow(workflowId, payload, options?)`
+
+Triggers an HTTP workflow execution.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `payload`: Request payload
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow execution response
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useTriggerWorkflow(workflowId, options?)`
+
+Triggers a workflow execution.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow execution response
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorkbook(workbookId, options?)`
+
+Fetches workbook details by ID.
+
+**Parameters:**
+- `workbookId`: ID of the workbook
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workbook object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorkflow(workflowId, options?)`
+
+Fetches workflow configuration by ID.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow configuration object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorksheet(worksheetId, options?)`
+
+Fetches worksheet details by ID.
+
+**Parameters:**
+- `worksheetId`: ID of the worksheet
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Worksheet object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+
+## Configuration
+
+### Default Query Configuration
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 3,
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes
+    },
+  },
+});
+```
+
+### Customizable Parameters
+
+All hooks accept standard TanStack React Query options:
+
+```ts
+interface QueryOptions {
+  enabled?: boolean;        // Enable/disable query
+  staleTime?: number;      // Duration (ms) before data is stale
+  gcTime?: number;         // Duration (ms) to keep data in cache
+  retry?: number | boolean; // Number of retries or disable retries
+  onSuccess?: (data: any) => void; // Success callback
+  onError?: (error: Error) => void; // Error callback
+}
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```tsx
+useUser({
+  onError: (error) => {
+    console.error('User fetch failed:', error.message);
+    // Custom error recovery logic
+  }
+});
+```
+
+### Manual Refetching
+
+```tsx
+function ManualRefetch() {
+  const { data, refetch } = useUser();
+  
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+## Re-exports
+
+This package re-exports core TanStack React Query utilities:
+
+```ts
+import { 
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+  ReactQueryDevtools 
+} from '@bluecopa/react';
+```
+
 ### Styling Guidelines
 - Use Tailwind CSS classes
 - Leverage CSS variables for theming

package/templates/latest/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-alpine AS production
+FROM node:22-alpine AS production
 
 # Set working directory
 WORKDIR /usr/src/app
@@ -7,7 +7,7 @@ WORKDIR /usr/src/app
 COPY package*.json ./
 
 # Install dependencies
-RUN npm install
+RUN npm install --no-audit --no-fund
 
 # Copy source code
 COPY . .

package/templates/latest/app/app.tsx

@@ -1,5 +1,6 @@
 import { Suspense, useEffect, useState } from 'react'
 import { reactQuery, ReactQueryDevtools, copaSetConfig } from "@bluecopa/react";
+import { Toaster } from "sonner";
 import RouteConfig from './routes';
 
 import './app.css'
@@ -32,7 +33,7 @@ export default function App(props: any) {
       apiBaseUrl: props.apiBaseUrl || import.meta.env.VITE_BLUECOPA_API_URL || 'https://develop.bluecopa.com',
       workspaceId: props.workspaceId || import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || '',
       accessToken: props.accessToken || copaUser?.accessToken || '',
-      userId: props.userId || ''
+      userId: props.userId || copaUser.userId || ''
     } as any);
   }, []);
 
@@ -41,6 +42,7 @@ export default function App(props: any) {
       <Suspense fallback={<div className="p-4 text-sm text-muted-foreground">Loading…</div>}>
         <RouteConfig />
         <ReactQueryDevtools initialIsOpen={false} />
+        <Toaster />
       </Suspense>
     </QueryClientProvider>
   )