create-bluecopa-react-app 1.0.12 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/package.json +1 -1
  2. package/templates/latest/Agent.md +639 -521
  3. package/templates/latest/app/routes/websocket.tsx +5 -4
  4. package/templates/latest/app/routes.tsx +5 -8
  5. package/templates/latest/components.json +1 -2
  6. package/templates/latest/dist/assets/{__federation_expose_App-B2IoFaIA.js → __federation_expose_App-BIH7hwj_.js} +3 -4
  7. package/templates/latest/dist/assets/{home-BBY02MnI.js → client-CsvW46cT.js} +18448 -929
  8. package/templates/latest/dist/assets/{index-CNNS7Foy.js → index-CFECuPSy.js} +3 -4
  9. package/templates/latest/dist/assets/remoteEntry.css +151 -19
  10. package/templates/latest/dist/assets/remoteEntry.js +1 -1
  11. package/templates/latest/dist/favicon.ico +0 -0
  12. package/templates/latest/dist/index.html +2 -3
  13. package/templates/latest/package-lock.json +203 -203
  14. package/templates/latest/package.json +1 -1
  15. package/templates/latest/dist/assets/client-LFBsfOjG.js +0 -2775
  16. package/templates/latest/dist/assets/index-D5og7-RT-BA7DwZw1.js +0 -9917
  17. package/templates/latest/dist/avatars/shadcn.svg +0 -6
  18. /package/templates/latest/app/routes/{home.tsx → dashboard.tsx} +0 -0
package/templates/latest/Agent.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this BlueCopa React application template.
4
4
 
5
+ ---
6
+
5
7
  ## 🏗️ Project Architecture Overview
6
8
 
7
9
  ### Core Stack
@@ -12,11 +14,48 @@ This guide helps AI assistants and developers understand the project structure,
12
14
  - **Vite 6** for build tooling
13
15
  - **TanStack Query** (via @bluecopa/react)
14
16
 
17
+ ---
18
+
19
+ ## 💡 UI Components & @bluecopa-ui Registry
20
+
21
+ This project uses [shadcn/ui](https://ui.shadcn.com/) to scaffold and manage UI component libraries, configured with an explicit support for the **@bluecopa-ui** component registry.
22
+
23
+ ### About the `@bluecopa-ui` Registry
24
+
25
+ The registry location is defined in your `components.json` file, mapping the registry name to a hosted registry endpoint:
26
+
27
+ ```json
28
+ {
29
+ ...
30
+ "registries": {
31
+ "@bluecopa-ui": "https://shadcn-ui-henna.vercel.app/r/{name}.json"
32
+ }
33
+ }
34
+ ```
35
+
36
+ - **@bluecopa-ui** registry extends the standard shadcn/ui workflow and provides a curated set of BlueCopa-centric UI components, patterns, and design tokens.
37
+ - When running any `npx shadcn@latest` CLI commands and passing `add` or `add registry`, you can use `@bluecopa-ui` as the registry source, e.g.:
38
+
39
+ ```bash
40
+ npx shadcn@latest add @bluecopa-ui/<component>
41
+ ```
42
+ - This enables streamlined upgrades, easy addition of company-specific components, and consistency with the BlueCopa Design System.
43
+
44
+ #### Benefits
45
+
46
+ - **Consistency:** Centralizes custom BlueCopa UI patterns and updates.
47
+ - **Discoverability:** Quickly add business-specific primitives, layouts, dashboards, and utilities.
48
+ - **Maintenance:** Receive improvements, fixes, and new patterns from BlueCopa UX engineering.
49
+
50
+ **Tip:** `@bluecopa-ui` can be used alongside the default shadcn registry. Specify which to use with `--registry` CLI flag.
51
+
52
+ ---
53
+
15
54
  ### Key Directories
16
55
  ```
17
56
  app/
18
57
  ├── components/ # Reusable UI components
19
- │ ├── ui/ # shadcn/ui components
58
+ │ ├── ui/ # shadcn/ui & @bluecopa-ui components
20
59
  │ ├── app-sidebar.tsx # Main navigation
21
60
  │ ├── data-table.tsx # TanStack Table wrapper
22
61
  │ └── chart-*.tsx # Recharts components
@@ -26,23 +65,25 @@ app/
26
65
  └── dashboard/ # Sample data and components
27
66
  ```
28
67
 
68
+ ---
69
+
29
70
  ## 🎨 Component Patterns
30
71
 
31
- ### shadcn/ui Components
32
- All UI components follow shadcn/ui patterns:
33
- - Located in `app/components/ui/`
34
- - Built on Radix UI primitives
35
- - Styled with Tailwind CSS
36
- - Use `cn()` utility for class merging
37
- - Support dark mode via CSS variables
72
+ ### shadcn/ui & @bluecopa-ui Components
73
+ - All base UI components reside in `app/components/ui/`
74
+ - Most are built atop [Radix UI](https://www.radix-ui.com/) primitives
75
+ - Styled using Tailwind CSS and support theme variables
76
+ - All component imports use the `@bluecopa-ui` registry if you fetch using `npx shadcn@latest add @bluecopa-ui/tooltip`
77
+ - Use the `cn()` utility for conditional styling
78
+ - Fully support dark mode and global CSS variables for design tokens
38
79
 
39
80
  ### Custom Components
40
81
  - Use TypeScript interfaces for props
41
- - Follow React best practices (hooks, memo, etc.)
42
- - Implement proper accessibility
43
- - Use semantic HTML elements
82
+ - Follow React best practices: hooks, `React.memo` as appropriate
83
+ - Implement full accessibility (aria attributes, keyboard nav)
84
+ - Use semantic HTML
44
85
 
45
- ### Example Component Structure
86
+ #### Example Component Structure
46
87
  ```tsx
47
88
  import { cn } from "~/lib/utils"
48
89
 
@@ -60,596 +101,673 @@ export function Component({ className, children }: ComponentProps) {
60
101
  }
61
102
  ```
62
103
 
104
+ ---
105
+
63
106
  ## 🔧 Development Patterns
64
107
 
65
108
  ### State Management
66
- - Use React hooks (useState, useReducer, useContext)
67
- - TanStack Query for server state
68
- - Local state for UI interactions
69
- - Avoid prop drilling with context
109
+ - Prefer React hooks (`useState`, `useReducer`, `useContext`)
110
+ - Use TanStack Query for server state
111
+ - Avoid prop drilling by using React Context
70
112
 
71
113
  ### Data Fetching
72
- - Use `@bluecopa/react` hooks for API calls
73
- - Implement loading and error states
74
- - Use TanStack Query for caching
75
- - Handle optimistic updates
76
- # @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)
77
-
78
- ## A Comprehensive React Query Integration for Bluecopa
79
-
80
- 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.
81
-
82
- ## Table of Contents
83
-
84
- - [@bluecopa/react ](#bluecopareact--)
85
- - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
86
- - [Table of Contents](#table-of-contents)
87
- - [Features](#features)
88
- - [Installation](#installation)
89
- - [Peer Dependencies](#peer-dependencies)
90
- - [Usage](#usage)
91
- - [Query Provider Setup](#query-provider-setup)
92
- - [Boilerplate Integration](#boilerplate-integration)
93
- - [Hook Examples](#hook-examples)
94
- - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
95
- - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
96
- - [API Documentation](#api-documentation)
97
- - [`useUser(options?)`](#useuseroptions)
98
- - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
99
- - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
100
- - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
101
- - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
102
- - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
103
- - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
104
- - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
105
- - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
106
- - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
107
- - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
108
- - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
109
- - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
110
- - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
111
- - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
112
- - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
113
- - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
114
- - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
115
- - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
116
- - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
117
- - [Configuration](#configuration)
118
- - [Default Query Configuration](#default-query-configuration)
119
- - [Customizable Parameters](#customizable-parameters)
120
- - [Advanced Usage](#advanced-usage)
121
- - [Error Handling](#error-handling)
122
- - [Manual Refetching](#manual-refetching)
123
- - [Re-exports](#re-exports)
124
- - [TypeScript Support](#typescript-support)
125
- - [Development](#development)
126
-
127
- ## Features
128
-
129
- - ✅ First-class TypeScript support with strict type definitions
130
- - 🔁 Seamless integration with TanStack React Query (v5+)
131
- - 🛡 Comprehensive error handling patterns
132
- - ⚙ Optimized default query configuration
133
- - 📦 Re-exports of core TanStack React Query utilities
134
- - 📊 Sample data preview capabilities
135
- - 🧩 Customizable query parameters (limit, caching, retries)
136
-
137
- ## Installation
138
-
139
- ```bash
140
- npm install @bluecopa/react
141
- # or with pnpm
142
- pnpm add @bluecopa/react
143
- ```
144
-
145
- ### Peer Dependencies
146
-
147
- This package requires the following in your application:
148
-
149
- ```bash
150
- npm install react@^18.0.0 react-dom@^18.0.0
151
- ```
152
-
153
- ## Usage
154
-
155
- ### Query Provider Setup
156
-
157
- Wrap your application with the React Query provider:
158
-
159
- ```tsx
160
- import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
161
-
162
- const queryClient = new QueryClient({
163
- defaultOptions: {
164
- queries: {
165
- staleTime: 60 * 1000, // 1 minute
166
- refetchOnWindowFocus: false,
167
- },
168
- },
169
- });
170
-
171
- function App() {
172
- return (
173
- <QueryClientProvider client={queryClient}>
174
- <YourApp />
175
- <ReactQueryDevtools initialIsOpen={false} />
176
- </QueryClientProvider>
177
- );
178
- }
179
- ```
180
-
181
- ### Boilerplate Integration
182
-
183
- For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
184
-
185
- ```tsx
186
- // src/providers/query-provider.tsx
187
- import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
188
- import { useEffect, useState } from "react";
189
-
190
- const { QueryClient, QueryClientProvider } = reactQuery;
191
-
192
- export default function QueryProvider({ children }: { children: React.ReactNode }) {
193
- const [queryClient] = useState(() => new QueryClient({
194
- defaultOptions: {
195
- queries: {
196
- staleTime: 60 * 1000, // 1 minute
197
- refetchOnWindowFocus: false,
198
- },
199
- },
200
- }));
201
-
202
- useEffect(() => {
203
- let copaUser: any = {};
204
- try {
205
- const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
206
- ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
207
- : "{}";
208
-
209
- copaUser = JSON.parse(copaToken);
210
- } catch (error) {
211
- console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
212
- }
213
-
214
- copaSetConfig({
215
- apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
216
- workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
217
- accessToken: copaUser?.accessToken || "",
218
- });
219
- }, []);
220
-
221
- return (
222
- <QueryClientProvider client={queryClient}>
223
- {children}
224
- <ReactQueryDevtools initialIsOpen={false} />
225
- </QueryClientProvider>
226
- );
227
- }
228
- ```
229
-
230
- **Required Environment Variables:**
231
-
232
- | Variable | Description | Example |
233
- |----------|-------------|---------|
234
- | `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
235
- | `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
236
- | `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
237
-
238
- **Example `.env` file:**
239
- ```
240
- VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
241
- VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
242
- VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
243
- ```
244
-
245
- Then wrap your application with this provider:
246
-
247
- ```tsx
248
- import QueryProvider from './providers/query-provider';
249
-
250
- function App() {
251
- return (
252
- <QueryProvider>
253
- <YourApp />
254
- </QueryProvider>
255
- );
256
- }
257
- ```
258
-
259
- This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
260
-
261
- ### Hook Examples
262
-
263
- #### `useUser` - Fetch authenticated user
264
-
265
- ```tsx
266
- import { useUser } from '@bluecopa/react';
267
-
268
- function UserProfile() {
269
- const { data, isLoading, error } = useUser({
270
- staleTime: 5 * 60 * 1000, // 5 minutes
271
- retry: 2
272
- });
273
-
274
- if (isLoading) return <div>Loading...</div>;
275
- if (error) return <div>Error: {error.message}</div>;
276
-
277
- return <div>Welcome, {data?.name}!</div>;
278
- }
279
- ```
280
-
281
- #### `useDataset` - Fetch dataset with query controls
282
-
283
- ```tsx
284
- import { useDataset } from '@bluecopa/react';
285
-
286
- function DatasetViewer({ datasetId }) {
287
- const { data, isLoading } = useDataset(datasetId, {
288
- limit: 500,
289
- staleTime: 10 * 60 * 1000 // 10 minutes
290
- });
291
-
292
- if (isLoading) return <div>Loading dataset...</div>;
293
- return <div>{data?.name} ({data?.records?.length} records)</div>;
294
- }
295
- ```
296
-
297
- ## API Documentation
298
-
299
- ### `useUser(options?)`
300
-
301
- Fetches authenticated user details with query controls.
302
-
303
- **Parameters:**
304
- - `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
305
-
306
- **Returns:**
307
- - `data`: User object or `undefined`
308
- - `isLoading`: Boolean indicating loading state
309
- - `error`: Error object if request failed
310
- - `refetch`: Function to manually trigger refetch
311
-
312
- ### `useDataset(datasetId, options?)`
114
+ - Use `@bluecopa/react` hooks for all API access
115
+ - Implement loading and error states at the component level
116
+ - Leverage TanStack Query caching and invalidation
117
+ - Support optimistic UI for updating server state where possible
118
+
119
+ ---
120
+
121
+ # @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)
122
+
123
+ ## A Comprehensive React Query Integration for BlueCopa
124
+
125
+ 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.
126
+
127
+ ---
128
+
129
+ ## Table of Contents
130
+
131
+ - [AI Agent Guide for BlueCopa React shadcn/ui Template](#ai-agent-guide-for-bluecopa-react-shadcnui-template)
132
+ - [🏗️ Project Architecture Overview](#️-project-architecture-overview)
133
+ - [Core Stack](#core-stack)
134
+ - [💡 UI Components \& @bluecopa-ui Registry](#-ui-components--bluecopa-ui-registry)
135
+ - [About the `@bluecopa-ui` Registry](#about-the-bluecopa-ui-registry)
136
+ - [Benefits](#benefits)
137
+ - [Key Directories](#key-directories)
138
+ - [🎨 Component Patterns](#-component-patterns)
139
+ - [shadcn/ui \& @bluecopa-ui Components](#shadcnui--bluecopa-ui-components)
140
+ - [Custom Components](#custom-components)
141
+ - [Example Component Structure](#example-component-structure)
142
+ - [🔧 Development Patterns](#-development-patterns)
143
+ - [State Management](#state-management)
144
+ - [Data Fetching](#data-fetching)
145
+ - [@bluecopa/react ](#bluecopareact--)
146
+ - [A Comprehensive React Query Integration for BlueCopa](#a-comprehensive-react-query-integration-for-bluecopa)
147
+ - [Table of Contents](#table-of-contents)
148
+ - [Features](#features)
149
+ - [Installation](#installation)
150
+ - [Peer Dependencies](#peer-dependencies)
151
+ - [Usage](#usage)
152
+ - [Query Provider Setup](#query-provider-setup)
153
+ - [Boilerplate Integration](#boilerplate-integration)
154
+ - [Adding a BlueCopa UI Component](#adding-a-bluecopa-ui-component)
155
+ - [Hook Examples](#hook-examples)
156
+ - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
157
+ - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
158
+ - [... *(rest of guide unchanged)*](#-rest-of-guide-unchanged)
159
+ - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
160
+ - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
161
+ - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
162
+ - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
163
+ - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
164
+ - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
165
+ - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
166
+ - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
167
+ - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
168
+ - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
169
+ - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
170
+ - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
171
+ - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
172
+ - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
173
+ - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
174
+ - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
175
+ - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
176
+ - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
177
+ - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
178
+ - [Configuration](#configuration)
179
+ - [Default Query Configuration](#default-query-configuration)
180
+ - [Customizable Parameters](#customizable-parameters)
181
+ - [Advanced Usage](#advanced-usage)
182
+ - [Error Handling](#error-handling)
183
+ - [Manual Refetching](#manual-refetching)
184
+ - [Re-exports](#re-exports)
185
+ - [Styling Guidelines](#styling-guidelines)
186
+ - [📊 Data Visualization](#-data-visualization)
187
+ - [Charts (Recharts)](#charts-recharts)
188
+ - [Tables (TanStack Table)](#tables-tanstack-table)
189
+ - [🎯 Common Tasks \& Solutions](#-common-tasks--solutions)
190
+ - [Adding New Pages](#adding-new-pages)
191
+ - [Adding New Components](#adding-new-components)
192
+ - [Working with Forms](#working-with-forms)
193
+ - [API Integration](#api-integration)
194
+ - [🚀 Performance Optimization](#-performance-optimization)
195
+ - [Code Splitting](#code-splitting)
196
+ - [Bundle Optimization](#bundle-optimization)
197
+ - [Runtime Performance](#runtime-performance)
198
+ - [🧪 Testing Strategies](#-testing-strategies)
199
+ - [Component Testing](#component-testing)
200
+ - [Integration Testing](#integration-testing)
201
+ - [🔒 Security Considerations](#-security-considerations)
202
+ - [Data Handling](#data-handling)
203
+ - [📱 Responsive Design](#-responsive-design)
204
+ - [Breakpoints](#breakpoints)
205
+ - [Layout Patterns](#layout-patterns)
206
+ - [🌙 Dark Mode Implementation](#-dark-mode-implementation)
207
+ - [Theme System](#theme-system)
208
+ - [Component Theming](#component-theming)
209
+ - [🐛 Debugging Tips](#-debugging-tips)
210
+ - [Common Issues](#common-issues)
211
+ - [Development Tools](#development-tools)
212
+ - [📚 Useful Resources](#-useful-resources)
213
+ - [Documentation](#documentation)
214
+ - [BlueCopa Specific](#bluecopa-specific)
215
+ - [🎯 Best Practices Summary](#-best-practices-summary)
216
+ - [🔄 Common Workflows](#-common-workflows)
217
+ - [Adding a New Feature](#adding-a-new-feature)
218
+ - [Debugging Issues](#debugging-issues)
219
+
220
+ ## Features
221
+
222
+ - ✅ First-class TypeScript support with strict type definitions
223
+ - 🔁 Seamless integration with TanStack React Query (v5+)
224
+ - 🛡 Comprehensive error handling patterns
225
+ - ⚙ Optimized default query configuration
226
+ - 📦 Re-exports of core TanStack React Query utilities
227
+ - 📊 Sample data preview capabilities
228
+ - 🧩 Customizable query parameters (limit, caching, retries)
229
+ - 🪄 Quickly use shadcn/ui and BlueCopa-specific components via `@bluecopa-ui` registry
230
+
231
+ ---
232
+
233
+ ## Installation
234
+
235
+ ```bash
236
+ npm install @bluecopa/react
237
+ # or with pnpm
238
+ pnpm add @bluecopa/react
239
+ ```
240
+
241
+ **To enable shadcn/ui with BlueCopa custom components (from @bluecopa-ui registry):**
242
+
243
+ ```bash
244
+ npx shadcn@latest add @bluecopa-ui/<component>
245
+ ```
246
+
247
+ This will fetch the component from the "@bluecopa-ui" registry endpoint declared in your `components.json`. This means you automatically get the most up-to-date BlueCopa patterns and design system building blocks.
248
+
249
+ ### Peer Dependencies
250
+
251
+ Install required peer dependencies:
252
+
253
+ ```bash
254
+ npm install react@^18.0.0 react-dom@^18.0.0
255
+ ```
256
+
257
+ ---
258
+
259
+ ## Usage
313
260
 
314
- Fetches dataset data by ID with configurable parameters.
261
+ ### Query Provider Setup
315
262
 
316
- **Parameters:**
317
- - `datasetId`: ID of the dataset to fetch
318
- - `options` (optional): Query options with:
319
- - `limit`: Maximum records to fetch
320
- - `staleTime`: Duration (ms) before data is considered stale
263
+ Wrap your application with the React Query provider:
321
264
 
322
- **Returns:**
323
- - `data`: Dataset object containing name and records
324
- - `isLoading`: Boolean indicating loading state
325
- - `error`: Error object if request failed
326
- - `refetch`: Function to manually trigger refetch
265
+ ```tsx
266
+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
267
+
268
+ const queryClient = new QueryClient({
269
+ defaultOptions: {
270
+ queries: {
271
+ staleTime: 60 * 1000, // 1 minute
272
+ refetchOnWindowFocus: false,
273
+ },
274
+ },
275
+ });
276
+
277
+ function App() {
278
+ return (
279
+ <QueryClientProvider client={queryClient}>
280
+ <YourApp />
281
+ <ReactQueryDevtools initialIsOpen={false} />
282
+ </QueryClientProvider>
283
+ );
284
+ }
285
+ ```
327
286
 
328
- ### `useDatasetSample(datasetId, options?)`
287
+ ### Boilerplate Integration
329
288
 
330
- Fetches a representative sample of dataset data.
289
+ For projects using the BlueCopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically and integrates all BlueCopa registry UI imports:
331
290
 
332
- **Parameters:**
333
- - `datasetId`: ID of the dataset
334
- - `options` (optional): Query options with `enabled` flag
291
+ ```tsx
292
+ // src/providers/query-provider.tsx
293
+ import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
294
+ import { useEffect, useState } from "react";
295
+
296
+ const { QueryClient, QueryClientProvider } = reactQuery;
297
+
298
+ export default function QueryProvider({ children }: { children: React.ReactNode }) {
299
+ const [queryClient] = useState(() => new QueryClient({
300
+ defaultOptions: {
301
+ queries: {
302
+ staleTime: 60 * 1000, // 1 minute
303
+ refetchOnWindowFocus: false,
304
+ },
305
+ },
306
+ }));
307
+
308
+ useEffect(() => {
309
+ let copaUser: any = {};
310
+ try {
311
+ const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
312
+ ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
313
+ : "{}";
314
+
315
+ copaUser = JSON.parse(copaToken);
316
+ } catch (error) {
317
+ console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
318
+ }
319
+
320
+ copaSetConfig({
321
+ apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
322
+ workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
323
+ accessToken: copaUser?.accessToken || "",
324
+ });
325
+ }, []);
335
326
 
336
- **Returns:**
337
- - `data`: Object containing sample data
338
- - `isLoading`: Boolean indicating loading state
339
- - `refetch`: Function to manually trigger refetch
327
+ return (
328
+ <QueryClientProvider client={queryClient}>
329
+ {children}
330
+ <ReactQueryDevtools initialIsOpen={false} />
331
+ </QueryClientProvider>
332
+ );
333
+ }
334
+ ```
340
335
 
341
- ### `useMetric(metricId, options?)`
336
+ **Required Environment Variables:**
342
337
 
343
- Fetches metric data by ID.
338
+ | Variable | Description | Example |
339
+ |----------|-------------|---------|
340
+ | `VITE_BLUECOPA_API_URL` | Base URL for BlueCopa API | `https://develop.bluecopa.com` |
341
+ | `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
342
+ | `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
344
343
 
345
- **Parameters:**
346
- - `metricId`: ID of the metric
347
- - `options` (optional): Query options
344
+ **Example `.env` file:**
345
+ ```
346
+ VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
347
+ VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
348
+ VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
349
+ ```
348
350
 
349
- **Returns:**
350
- - `data`: Metric object with name and value
351
- - `isLoading`: Boolean indicating loading state
352
- - `error`: Error object if request failed
353
- - `refetch`: Function to manually trigger refetch
351
+ Then wrap your application with this provider:
354
352
 
355
- ### `useInputTable(inputTableId, options?)`
353
+ ```tsx
354
+ import QueryProvider from './providers/query-provider';
356
355
 
357
- Fetches input table data with limit parameters.
356
+ function App() {
357
+ return (
358
+ <QueryProvider>
359
+ <YourApp />
360
+ </QueryProvider>
361
+ );
362
+ }
363
+ ```
358
364
 
359
- **Parameters:**
360
- - `inputTableId`: ID of the input table
361
- - `options` (optional): Query options with `limitParams`:
362
- - `limit`: Maximum rows to fetch
363
- - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
365
+ This setup automatically configures both the BlueCopa API client and enables seamless usage of BlueCopa UI primitives pulled from the custom registry.
364
366
 
365
- **Returns:**
366
- - `data`: Input table object with rows
367
- - `isLoading`: Boolean indicating loading state
368
- - `error`: Error object if request failed
369
- - `refetch`: Function to manually trigger refetch
367
+ ---
370
368
 
371
- ### `useGetFileUrlByFileId(fileId, options?)`
369
+ ### Adding a BlueCopa UI Component
372
370
 
373
- Fetches the URL for a file by its ID.
371
+ To add a BlueCopa custom UI primitive (e.g., "copa-card") to your project, use:
374
372
 
375
- **Parameters:**
376
- - `fileId`: ID of the file to fetch URL for
377
- - `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
373
+ ```bash
374
+ npx shadcn@latest add @bluecopa-ui/pagination-block
375
+ ```
378
376
 
379
- **Returns:**
380
- - `data`: Object containing file URL
381
- - `isLoading`: Boolean indicating loading state
382
- - `error`: Error object if request failed
383
- - `refetch`: Function to manually trigger refetch
377
+ The CLI pulls the latest [copa-card](https://shadcn-ui-henna.vercel.app/r/copa-card.json) definition from the registry as specified in `components.json`, and installs it to `app/components/ui/`.
384
378
 
385
- ### `useGetPublishedWorkbookById(workbookId, options?)`
379
+ ---
386
380
 
387
- Fetches published workbook details by ID.
381
+ ### Hook Examples
388
382
 
389
- **Parameters:**
390
- - `workbookId`: ID of the published workbook
391
- - `options` (optional): Query options
383
+ #### `useUser` - Fetch authenticated user
392
384
 
393
- **Returns:**
394
- - `data`: Published workbook object
395
- - `isLoading`: Boolean indicating loading state
396
- - `error`: Error object if request failed
397
- - `refetch`: Function to manually trigger refetch
385
+ ```tsx
386
+ import { useUser } from '@bluecopa/react';
387
+
388
+ function UserProfile() {
389
+ const { data, isLoading, error } = useUser({
390
+ staleTime: 5 * 60 * 1000, // 5 minutes
391
+ retry: 2
392
+ });
393
+
394
+ if (isLoading) return <div>Loading...</div>;
395
+ if (error) return <div>Error: {error.message}</div>;
396
+
397
+ return <div>Welcome, {data?.name}!</div>;
398
+ }
399
+ ```
398
400
 
399
- ### `useGetTableById(tableId, options?)`
401
+ #### `useDataset` - Fetch dataset with query controls
400
402
 
401
- Fetches table metadata by ID.
403
+ ```tsx
404
+ import { useDataset } from '@bluecopa/react';
405
+
406
+ function DatasetViewer({ datasetId }) {
407
+ const { data, isLoading } = useDataset(datasetId, {
408
+ limit: 500,
409
+ staleTime: 10 * 60 * 1000 // 10 minutes
410
+ });
411
+
412
+ if (isLoading) return <div>Loading dataset...</div>;
413
+ return <div>{data?.name} ({data?.records?.length} records)</div>;
414
+ }
415
+ ```
402
416
 
403
- **Parameters:**
404
- - `tableId`: ID of the table
405
- - `options` (optional): Query options
417
+ ---
406
418
 
407
- **Returns:**
408
- - `data`: Table metadata object
409
- - `isLoading`: Boolean indicating loading state
410
- - `error`: Error object if request failed
411
- - `refetch`: Function to manually trigger refetch
419
+ ## ... *(rest of guide unchanged)*
412
420
 
413
- ### `useGetWorkbooksByType(workbookType, options?)`
421
+ The rest of this guide covers all @bluecopa/react data hooks, configuration, testing, and best practices as before. For adding or updating UI primitives, always prefer `@bluecopa-ui` registry where available to match BlueCopa's latest design system and component standards.
414
422
 
415
- Fetches workbooks filtered by type.
416
423
 
417
- **Parameters:**
418
- - `workbookType`: Type of workbooks to fetch
419
- - `options` (optional): Query options
424
+ **Returns:**
425
+ - `data`: User object or `undefined`
426
+ - `isLoading`: Boolean indicating loading state
427
+ - `error`: Error object if request failed
428
+ - `refetch`: Function to manually trigger refetch
420
429
 
421
- **Returns:**
422
- - `data`: Array of workbook objects
423
- - `isLoading`: Boolean indicating loading state
424
- - `error`: Error object if request failed
425
- - `refetch`: Function to manually trigger refetch
430
+ ### `useDataset(datasetId, options?)`
426
431
 
427
- ### `useGetWorkflowInstanceStatusById(instanceId, options?)`
432
+ Fetches dataset data by ID with configurable parameters.
428
433
 
429
- Fetches workflow instance status by ID.
434
+ **Parameters:**
435
+ - `datasetId`: ID of the dataset to fetch
436
+ - `options` (optional): Query options with:
437
+ - `limit`: Maximum records to fetch
438
+ - `staleTime`: Duration (ms) before data is considered stale
430
439
 
431
- **Parameters:**
432
- - `instanceId`: ID of the workflow instance
433
- - `options` (optional): Query options
440
+ **Returns:**
441
+ - `data`: Dataset object containing name and records
442
+ - `isLoading`: Boolean indicating loading state
443
+ - `error`: Error object if request failed
444
+ - `refetch`: Function to manually trigger refetch
434
445
 
435
- **Returns:**
436
- - `data`: Workflow status object
437
- - `isLoading`: Boolean indicating loading state
438
- - `error`: Error object if request failed
439
- - `refetch`: Function to manually trigger refetch
446
+ ### `useDatasetSample(datasetId, options?)`
440
447
 
441
- ### `useGetWorksheets(options?)`
448
+ Fetches a representative sample of dataset data.
442
449
 
443
- Fetches all available worksheets.
450
+ **Parameters:**
451
+ - `datasetId`: ID of the dataset
452
+ - `options` (optional): Query options with `enabled` flag
444
453
 
445
- **Parameters:**
446
- - `options` (optional): Query options
454
+ **Returns:**
455
+ - `data`: Object containing sample data
456
+ - `isLoading`: Boolean indicating loading state
457
+ - `refetch`: Function to manually trigger refetch
447
458
 
448
- **Returns:**
449
- - `data`: Array of worksheet objects
450
- - `isLoading`: Boolean indicating loading state
451
- - `error`: Error object if request failed
452
- - `refetch`: Function to manually trigger refetch
459
+ ### `useMetric(metricId, options?)`
453
460
 
454
- ### `useGetWorksheetsByType(worksheetType, options?)`
461
+ Fetches metric data by ID.
455
462
 
456
- Fetches worksheets filtered by type.
463
+ **Parameters:**
464
+ - `metricId`: ID of the metric
465
+ - `options` (optional): Query options
457
466
 
458
- **Parameters:**
459
- - `worksheetType`: Type of worksheets to fetch
460
- - `options` (optional): Query options
467
+ **Returns:**
468
+ - `data`: Metric object with name and value
469
+ - `isLoading`: Boolean indicating loading state
470
+ - `error`: Error object if request failed
471
+ - `refetch`: Function to manually trigger refetch
461
472
 
462
- **Returns:**
463
- - `data`: Array of worksheet objects
464
- - `isLoading`: Boolean indicating loading state
465
- - `error`: Error object if request failed
466
- - `refetch`: Function to manually trigger refetch
473
+ ### `useInputTable(inputTableId, options?)`
467
474
 
468
- ### `useRunDefinition(definitionId, options?)`
475
+ Fetches input table data with limit parameters.
469
476
 
470
- Executes a run definition.
477
+ **Parameters:**
478
+ - `inputTableId`: ID of the input table
479
+ - `options` (optional): Query options with `limitParams`:
480
+ - `limit`: Maximum rows to fetch
481
+ - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
471
482
 
472
- **Parameters:**
473
- - `definitionId`: ID of the run definition
474
- - `options` (optional): Query options
483
+ **Returns:**
484
+ - `data`: Input table object with rows
485
+ - `isLoading`: Boolean indicating loading state
486
+ - `error`: Error object if request failed
487
+ - `refetch`: Function to manually trigger refetch
475
488
 
476
- **Returns:**
477
- - `data`: Execution result
478
- - `isLoading`: Boolean indicating loading state
479
- - `error`: Error object if request failed
480
- - `refetch`: Function to manually trigger refetch
489
+ ### `useGetFileUrlByFileId(fileId, options?)`
481
490
 
482
- ### `useRunPublishedDefinition(publishedDefinitionId, options?)`
491
+ Fetches the URL for a file by its ID.
483
492
 
484
- Executes a published run definition.
493
+ **Parameters:**
494
+ - `fileId`: ID of the file to fetch URL for
495
+ - `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
485
496
 
486
- **Parameters:**
487
- - `publishedDefinitionId`: ID of the published definition
488
- - `options` (optional): Query options
497
+ **Returns:**
498
+ - `data`: Object containing file URL
499
+ - `isLoading`: Boolean indicating loading state
500
+ - `error`: Error object if request failed
501
+ - `refetch`: Function to manually trigger refetch
489
502
 
490
- **Returns:**
491
- - `data`: Execution result
492
- - `isLoading`: Boolean indicating loading state
493
- - `error`: Error object if request failed
494
- - `refetch`: Function to manually trigger refetch
503
+ ### `useGetPublishedWorkbookById(workbookId, options?)`
495
504
 
496
- ### `useRunSampleDefinition(sampleDefinitionId, options?)`
505
+ Fetches published workbook details by ID.
497
506
 
498
- Executes a sample run definition.
507
+ **Parameters:**
508
+ - `workbookId`: ID of the published workbook
509
+ - `options` (optional): Query options
499
510
 
500
- **Parameters:**
501
- - `sampleDefinitionId`: ID of the sample definition
502
- - `options` (optional): Query options
511
+ **Returns:**
512
+ - `data`: Published workbook object
513
+ - `isLoading`: Boolean indicating loading state
514
+ - `error`: Error object if request failed
515
+ - `refetch`: Function to manually trigger refetch
503
516
 
504
- **Returns:**
505
- - `data`: Sample execution result
506
- - `isLoading`: Boolean indicating loading state
507
- - `error`: Error object if request failed
508
- - `refetch`: Function to manually trigger refetch
517
+ ### `useGetTableById(tableId, options?)`
509
518
 
510
- ### `useTriggerHttpWorkflow(workflowId, payload, options?)`
519
+ Fetches table metadata by ID.
511
520
 
512
- Triggers an HTTP workflow execution.
521
+ **Parameters:**
522
+ - `tableId`: ID of the table
523
+ - `options` (optional): Query options
513
524
 
514
- **Parameters:**
515
- - `workflowId`: ID of the workflow
516
- - `payload`: Request payload
517
- - `options` (optional): Query options
525
+ **Returns:**
526
+ - `data`: Table metadata object
527
+ - `isLoading`: Boolean indicating loading state
528
+ - `error`: Error object if request failed
529
+ - `refetch`: Function to manually trigger refetch
518
530
 
519
- **Returns:**
520
- - `data`: Workflow execution response
521
- - `isLoading`: Boolean indicating loading state
522
- - `error`: Error object if request failed
523
- - `refetch`: Function to manually trigger refetch
531
+ ### `useGetWorkbooksByType(workbookType, options?)`
524
532
 
525
- ### `useTriggerWorkflow(workflowId, options?)`
533
+ Fetches workbooks filtered by type.
526
534
 
527
- Triggers a workflow execution.
535
+ **Parameters:**
536
+ - `workbookType`: Type of workbooks to fetch
537
+ - `options` (optional): Query options
528
538
 
529
- **Parameters:**
530
- - `workflowId`: ID of the workflow
531
- - `options` (optional): Query options
539
+ **Returns:**
540
+ - `data`: Array of workbook objects
541
+ - `isLoading`: Boolean indicating loading state
542
+ - `error`: Error object if request failed
543
+ - `refetch`: Function to manually trigger refetch
532
544
 
533
- **Returns:**
534
- - `data`: Workflow execution response
535
- - `isLoading`: Boolean indicating loading state
536
- - `error`: Error object if request failed
537
- - `refetch`: Function to manually trigger refetch
545
+ ### `useGetWorkflowInstanceStatusById(instanceId, options?)`
538
546
 
539
- ### `useWorkbook(workbookId, options?)`
547
+ Fetches workflow instance status by ID.
540
548
 
541
- Fetches workbook details by ID.
549
+ **Parameters:**
550
+ - `instanceId`: ID of the workflow instance
551
+ - `options` (optional): Query options
542
552
 
543
- **Parameters:**
544
- - `workbookId`: ID of the workbook
545
- - `options` (optional): Query options
553
+ **Returns:**
554
+ - `data`: Workflow status object
555
+ - `isLoading`: Boolean indicating loading state
556
+ - `error`: Error object if request failed
557
+ - `refetch`: Function to manually trigger refetch
546
558
 
547
- **Returns:**
548
- - `data`: Workbook object
549
- - `isLoading`: Boolean indicating loading state
550
- - `error`: Error object if request failed
551
- - `refetch`: Function to manually trigger refetch
559
+ ### `useGetWorksheets(options?)`
552
560
 
553
- ### `useWorkflow(workflowId, options?)`
561
+ Fetches all available worksheets.
554
562
 
555
- Fetches workflow configuration by ID.
563
+ **Parameters:**
564
+ - `options` (optional): Query options
556
565
 
557
- **Parameters:**
558
- - `workflowId`: ID of the workflow
559
- - `options` (optional): Query options
566
+ **Returns:**
567
+ - `data`: Array of worksheet objects
568
+ - `isLoading`: Boolean indicating loading state
569
+ - `error`: Error object if request failed
570
+ - `refetch`: Function to manually trigger refetch
560
571
 
561
- **Returns:**
562
- - `data`: Workflow configuration object
563
- - `isLoading`: Boolean indicating loading state
564
- - `error`: Error object if request failed
565
- - `refetch`: Function to manually trigger refetch
572
+ ### `useGetWorksheetsByType(worksheetType, options?)`
566
573
 
567
- ### `useWorksheet(worksheetId, options?)`
574
+ Fetches worksheets filtered by type.
568
575
 
569
- Fetches worksheet details by ID.
576
+ **Parameters:**
577
+ - `worksheetType`: Type of worksheets to fetch
578
+ - `options` (optional): Query options
570
579
 
571
- **Parameters:**
572
- - `worksheetId`: ID of the worksheet
573
- - `options` (optional): Query options
580
+ **Returns:**
581
+ - `data`: Array of worksheet objects
582
+ - `isLoading`: Boolean indicating loading state
583
+ - `error`: Error object if request failed
584
+ - `refetch`: Function to manually trigger refetch
574
585
 
575
- **Returns:**
576
- - `data`: Worksheet object
577
- - `isLoading`: Boolean indicating loading state
578
- - `error`: Error object if request failed
579
- - `refetch`: Function to manually trigger refetch
586
+ ### `useRunDefinition(definitionId, options?)`
580
587
 
581
-
582
- ## Configuration
583
-
584
- ### Default Query Configuration
585
-
586
- ```tsx
587
- const queryClient = new QueryClient({
588
- defaultOptions: {
589
- queries: {
590
- retry: 3,
591
- staleTime: 1000 * 60 * 5, // 5 minutes
592
- gcTime: 1000 * 60 * 10, // 10 minutes
593
- },
594
- },
595
- });
596
- ```
597
-
598
- ### Customizable Parameters
599
-
600
- All hooks accept standard TanStack React Query options:
601
-
602
- ```ts
603
- interface QueryOptions {
604
- enabled?: boolean; // Enable/disable query
605
- staleTime?: number; // Duration (ms) before data is stale
606
- gcTime?: number; // Duration (ms) to keep data in cache
607
- retry?: number | boolean; // Number of retries or disable retries
608
- onSuccess?: (data: any) => void; // Success callback
609
- onError?: (error: Error) => void; // Error callback
610
- }
611
- ```
612
-
613
- ## Advanced Usage
614
-
615
- ### Error Handling
616
-
617
- ```tsx
618
- useUser({
619
- onError: (error) => {
620
- console.error('User fetch failed:', error.message);
621
- // Custom error recovery logic
622
- }
623
- });
624
- ```
625
-
626
- ### Manual Refetching
627
-
628
- ```tsx
629
- function ManualRefetch() {
630
- const { data, refetch } = useUser();
631
-
632
- return (
633
- <div>
634
- <button onClick={() => refetch()}>Refresh</button>
635
- </div>
636
- );
637
- }
638
- ```
639
-
640
- ## Re-exports
641
-
642
- This package re-exports core TanStack React Query utilities:
643
-
644
- ```ts
645
- import {
646
- useQuery,
647
- useMutation,
648
- QueryClient,
649
- QueryClientProvider,
650
- ReactQueryDevtools
651
- } from '@bluecopa/react';
652
- ```
588
+ Executes a run definition.
589
+
590
+ **Parameters:**
591
+ - `definitionId`: ID of the run definition
592
+ - `options` (optional): Query options
593
+
594
+ **Returns:**
595
+ - `data`: Execution result
596
+ - `isLoading`: Boolean indicating loading state
597
+ - `error`: Error object if request failed
598
+ - `refetch`: Function to manually trigger refetch
599
+
600
+ ### `useRunPublishedDefinition(publishedDefinitionId, options?)`
601
+
602
+ Executes a published run definition.
603
+
604
+ **Parameters:**
605
+ - `publishedDefinitionId`: ID of the published definition
606
+ - `options` (optional): Query options
607
+
608
+ **Returns:**
609
+ - `data`: Execution result
610
+ - `isLoading`: Boolean indicating loading state
611
+ - `error`: Error object if request failed
612
+ - `refetch`: Function to manually trigger refetch
613
+
614
+ ### `useRunSampleDefinition(sampleDefinitionId, options?)`
615
+
616
+ Executes a sample run definition.
617
+
618
+ **Parameters:**
619
+ - `sampleDefinitionId`: ID of the sample definition
620
+ - `options` (optional): Query options
621
+
622
+ **Returns:**
623
+ - `data`: Sample execution result
624
+ - `isLoading`: Boolean indicating loading state
625
+ - `error`: Error object if request failed
626
+ - `refetch`: Function to manually trigger refetch
627
+
628
+ ### `useTriggerHttpWorkflow(workflowId, payload, options?)`
629
+
630
+ Triggers an HTTP workflow execution.
631
+
632
+ **Parameters:**
633
+ - `workflowId`: ID of the workflow
634
+ - `payload`: Request payload
635
+ - `options` (optional): Query options
636
+
637
+ **Returns:**
638
+ - `data`: Workflow execution response
639
+ - `isLoading`: Boolean indicating loading state
640
+ - `error`: Error object if request failed
641
+ - `refetch`: Function to manually trigger refetch
642
+
643
+ ### `useTriggerWorkflow(workflowId, options?)`
644
+
645
+ Triggers a workflow execution.
646
+
647
+ **Parameters:**
648
+ - `workflowId`: ID of the workflow
649
+ - `options` (optional): Query options
650
+
651
+ **Returns:**
652
+ - `data`: Workflow execution response
653
+ - `isLoading`: Boolean indicating loading state
654
+ - `error`: Error object if request failed
655
+ - `refetch`: Function to manually trigger refetch
656
+
657
+ ### `useWorkbook(workbookId, options?)`
658
+
659
+ Fetches workbook details by ID.
660
+
661
+ **Parameters:**
662
+ - `workbookId`: ID of the workbook
663
+ - `options` (optional): Query options
664
+
665
+ **Returns:**
666
+ - `data`: Workbook object
667
+ - `isLoading`: Boolean indicating loading state
668
+ - `error`: Error object if request failed
669
+ - `refetch`: Function to manually trigger refetch
670
+
671
+ ### `useWorkflow(workflowId, options?)`
672
+
673
+ Fetches workflow configuration by ID.
674
+
675
+ **Parameters:**
676
+ - `workflowId`: ID of the workflow
677
+ - `options` (optional): Query options
678
+
679
+ **Returns:**
680
+ - `data`: Workflow configuration object
681
+ - `isLoading`: Boolean indicating loading state
682
+ - `error`: Error object if request failed
683
+ - `refetch`: Function to manually trigger refetch
684
+
685
+ ### `useWorksheet(worksheetId, options?)`
686
+
687
+ Fetches worksheet details by ID.
688
+
689
+ **Parameters:**
690
+ - `worksheetId`: ID of the worksheet
691
+ - `options` (optional): Query options
692
+
693
+ **Returns:**
694
+ - `data`: Worksheet object
695
+ - `isLoading`: Boolean indicating loading state
696
+ - `error`: Error object if request failed
697
+ - `refetch`: Function to manually trigger refetch
698
+
699
+
700
+ ## Configuration
701
+
702
+ ### Default Query Configuration
703
+
704
+ ```tsx
705
+ const queryClient = new QueryClient({
706
+ defaultOptions: {
707
+ queries: {
708
+ retry: 3,
709
+ staleTime: 1000 * 60 * 5, // 5 minutes
710
+ gcTime: 1000 * 60 * 10, // 10 minutes
711
+ },
712
+ },
713
+ });
714
+ ```
715
+
716
+ ### Customizable Parameters
717
+
718
+ All hooks accept standard TanStack React Query options:
719
+
720
+ ```ts
721
+ interface QueryOptions {
722
+ enabled?: boolean; // Enable/disable query
723
+ staleTime?: number; // Duration (ms) before data is stale
724
+ gcTime?: number; // Duration (ms) to keep data in cache
725
+ retry?: number | boolean; // Number of retries or disable retries
726
+ onSuccess?: (data: any) => void; // Success callback
727
+ onError?: (error: Error) => void; // Error callback
728
+ }
729
+ ```
730
+
731
+ ## Advanced Usage
732
+
733
+ ### Error Handling
734
+
735
+ ```tsx
736
+ useUser({
737
+ onError: (error) => {
738
+ console.error('User fetch failed:', error.message);
739
+ // Custom error recovery logic
740
+ }
741
+ });
742
+ ```
743
+
744
+ ### Manual Refetching
745
+
746
+ ```tsx
747
+ function ManualRefetch() {
748
+ const { data, refetch } = useUser();
749
+
750
+ return (
751
+ <div>
752
+ <button onClick={() => refetch()}>Refresh</button>
753
+ </div>
754
+ );
755
+ }
756
+ ```
757
+
758
+ ## Re-exports
759
+
760
+ This package re-exports core TanStack React Query utilities:
761
+
762
+ ```ts
763
+ import {
764
+ useQuery,
765
+ useMutation,
766
+ QueryClient,
767
+ QueryClientProvider,
768
+ ReactQueryDevtools
769
+ } from '@bluecopa/react';
770
+ ```
653
771
 
654
772
  ### Styling Guidelines
655
773
  - Use Tailwind CSS classes