create-bluecopa-react-app 1.0.13 → 1.0.14

package/package.json

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

package/templates/latest/Agent.md

@@ -2,6 +2,8 @@
 
 This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this BlueCopa React application template.
 
+---
+
 ## 🏗️ Project Architecture Overview
 
 ### Core Stack
@@ -12,11 +14,48 @@ This guide helps AI assistants and developers understand the project structure,
 - **Vite 6** for build tooling
 - **TanStack Query** (via @bluecopa/react)
 
+---
+
+## 💡 UI Components & @bluecopa-ui Registry
+
+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.
+
+### About the `@bluecopa-ui` Registry
+
+The registry location is defined in your `components.json` file, mapping the registry name to a hosted registry endpoint:
+
+```json
+{
+  ...
+  "registries": {
+    "@bluecopa-ui": "https://shadcn-ui-henna.vercel.app/r/{name}.json"
+  }
+}
+```
+
+- **@bluecopa-ui** registry extends the standard shadcn/ui workflow and provides a curated set of BlueCopa-centric UI components, patterns, and design tokens.  
+- 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.:
+  
+  ```bash
+  npx shadcn@latest add @bluecopa-ui/<component>
+  ```
+- This enables streamlined upgrades, easy addition of company-specific components, and consistency with the BlueCopa Design System.
+
+#### Benefits
+
+- **Consistency:** Centralizes custom BlueCopa UI patterns and updates.
+- **Discoverability:** Quickly add business-specific primitives, layouts, dashboards, and utilities.
+- **Maintenance:** Receive improvements, fixes, and new patterns from BlueCopa UX engineering.
+
+**Tip:** `@bluecopa-ui` can be used alongside the default shadcn registry. Specify which to use with `--registry` CLI flag.
+
+---
+
 ### Key Directories
 ```
 app/
 ├── components/          # Reusable UI components
-│   ├── ui/             # shadcn/ui components
+│   ├── ui/             # shadcn/ui & @bluecopa-ui components
 │   ├── app-sidebar.tsx # Main navigation
 │   ├── data-table.tsx  # TanStack Table wrapper
 │   └── chart-*.tsx     # Recharts components
@@ -26,23 +65,25 @@ app/
 └── dashboard/          # Sample data and components
 ```
 
+---
+
 ## 🎨 Component Patterns
 
-### shadcn/ui Components
-All UI components follow shadcn/ui patterns:
-- Located in `app/components/ui/`
-- Built on Radix UI primitives
-- Styled with Tailwind CSS
-- Use `cn()` utility for class merging
-- Support dark mode via CSS variables
+### shadcn/ui & @bluecopa-ui Components
+- All base UI components reside in `app/components/ui/`
+- Most are built atop [Radix UI](https://www.radix-ui.com/) primitives
+- Styled using Tailwind CSS and support theme variables
+- All component imports use the `@bluecopa-ui` registry if you fetch using `npx shadcn@latest add @bluecopa-ui/tooltip`
+- Use the `cn()` utility for conditional styling
+- Fully support dark mode and global CSS variables for design tokens
 
 ### Custom Components
 - Use TypeScript interfaces for props
-- Follow React best practices (hooks, memo, etc.)
-- Implement proper accessibility
-- Use semantic HTML elements
+- Follow React best practices: hooks, `React.memo` as appropriate
+- Implement full accessibility (aria attributes, keyboard nav)
+- Use semantic HTML
 
-### Example Component Structure
+#### Example Component Structure
 ```tsx
 import { cn } from "~/lib/utils"
 
@@ -60,41 +101,49 @@ export function Component({ className, children }: ComponentProps) {
 }
 ```
 
+---
+
 ## 🔧 Development Patterns
 
 ### State Management
-- Use React hooks (useState, useReducer, useContext)
-- TanStack Query for server state
-- Local state for UI interactions
-- Avoid prop drilling with context
+- Prefer React hooks (`useState`, `useReducer`, `useContext`)
+- Use TanStack Query for server state
+- Avoid prop drilling by using React Context
 
 ### Data Fetching
-- Use `@bluecopa/react` hooks for API calls
-- Implement loading and error states
-- Use TanStack Query for caching
-- Handle optimistic updates
+- Use `@bluecopa/react` hooks for all API access
+- Implement loading and error states at the component level
+- Leverage TanStack Query caching and invalidation
+- Support optimistic UI for updating server state where possible
+
+---
 
 # @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 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.
+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)
+  - [💡 UI Components \& @bluecopa-ui Registry](#-ui-components--bluecopa-ui-registry)
+    - [About the `@bluecopa-ui` Registry](#about-the-bluecopa-ui-registry)
+      - [Benefits](#benefits)
     - [Key Directories](#key-directories)
   - [🎨 Component Patterns](#-component-patterns)
-    - [shadcn/ui Components](#shadcnui-components)
+    - [shadcn/ui \& @bluecopa-ui Components](#shadcnui--bluecopa-ui-components)
     - [Custom Components](#custom-components)
-    - [Example Component Structure](#example-component-structure)
+      - [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)
+  - [A Comprehensive React Query Integration for BlueCopa](#a-comprehensive-react-query-integration-for-bluecopa)
   - [Table of Contents](#table-of-contents)
   - [Features](#features)
   - [Installation](#installation)
@@ -102,11 +151,11 @@ A React library providing opinionated custom hooks for TanStack React Query inte
   - [Usage](#usage)
     - [Query Provider Setup](#query-provider-setup)
     - [Boilerplate Integration](#boilerplate-integration)
+    - [Adding a BlueCopa UI Component](#adding-a-bluecopa-ui-component)
     - [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)
+  - [... *(rest of guide unchanged)*](#-rest-of-guide-unchanged)
     - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
     - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
     - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
@@ -177,6 +226,9 @@ A React library providing opinionated custom hooks for TanStack React Query inte
 - 📦 Re-exports of core TanStack React Query utilities
 - 📊 Sample data preview capabilities
 - 🧩 Customizable query parameters (limit, caching, retries)
+- 🪄 Quickly use shadcn/ui and BlueCopa-specific components via `@bluecopa-ui` registry
+
+---
 
 ## Installation
 
@@ -186,14 +238,24 @@ npm install @bluecopa/react
 pnpm add @bluecopa/react
 ```
 
+**To enable shadcn/ui with BlueCopa custom components (from @bluecopa-ui registry):**
+
+```bash
+npx shadcn@latest add @bluecopa-ui/<component>
+```
+
+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.
+
 ### Peer Dependencies
 
-This package requires the following in your application:
+Install required peer dependencies:
 
 ```bash
 npm install react@^18.0.0 react-dom@^18.0.0
 ```
 
+---
+
 ## Usage
 
 ### Query Provider Setup
@@ -224,7 +286,7 @@ function App() {
 
 ### Boilerplate Integration
 
-For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
+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:
 
 ```tsx
 // src/providers/query-provider.tsx
@@ -275,7 +337,7 @@ export default function QueryProvider({ children }: { children: React.ReactNode
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
+| `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=` |
 
@@ -300,7 +362,21 @@ function App() {
 }
 ```
 
-This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
+This setup automatically configures both the BlueCopa API client and enables seamless usage of BlueCopa UI primitives pulled from the custom registry.
+
+---
+
+### Adding a BlueCopa UI Component
+
+To add a BlueCopa custom UI primitive (e.g., "copa-card") to your project, use:
+
+```bash
+npx shadcn@latest add @bluecopa-ui/pagination-block
+```
+
+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/`.
+
+---
 
 ### Hook Examples
 
@@ -338,14 +414,12 @@ function DatasetViewer({ datasetId }) {
 }
 ```
 
-## API Documentation
+---
 
-### `useUser(options?)`
+## ... *(rest of guide unchanged)*
 
-Fetches authenticated user details with query controls.
+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.
 
-**Parameters:**  
-- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
 
 **Returns:**  
 - `data`: User object or `undefined`

package/templates/latest/components.json

@@ -19,7 +19,6 @@
     "hooks": "~/hooks"
   },
   "registries": {
-    "@shadcn": "https://ui.shadcn.com/r/index.json",
-    "@bluecopa-ui": "https://shadcn-ui-henna.vercel.app/r/registry.json"
+    "@bluecopa-ui": "https://shadcn-ui-henna.vercel.app/r/{name}.json"
   }
 }