npm package: @spaceinvoices/react-ui
Description: Space Invoices UI components - copy-paste distribution with CLI support
Latest version: 0.4.34

# @spaceinvoices/react-ui - Space Invoices React UI Kit

> **Copy-paste React UI for the Space Invoices API**

50+ installable components for building invoicing applications with the Space Invoices API. Includes forms, tables, dashboard charts, and more - all designed to be copied into your project for full customization.

## Philosophy

This package is a **CLI installer and source registry**, not a conventional runtime component library. The intended flow is:

1. initialize your app with the CLI
2. add only the components you need
3. own the copied source inside your app

These components are **designed to be copied**, not imported from `node_modules` at runtime:

- **Full ownership** - Modify freely without breaking changes
- **Complete customization** - Change behavior and structure
- **No version conflicts** - You control when to update
- **Zero lock-in** - Components work standalone in your codebase

**Note**: Components are built on **shadcn/ui primitives**. Bring your own shadcn/ui components or use any alternative. The CLI can copy compatible `components/ui/` primitives when needed, but teams using their own design system can swap those imports after install.

## Quick Start (CLI - Recommended)

The easiest way to get started is using the CLI:

```bash
# Initialize in your project
npx @spaceinvoices/react-ui init

# Add components as needed
npx @spaceinvoices/react-ui add customers/create-customer-form
npx @spaceinvoices/react-ui add invoices/create-invoice-form
npx @spaceinvoices/react-ui add table/data-table

# See all available components
npx @spaceinvoices/react-ui list
```

The CLI will:
- Create `spaceinvoices.json` config with your preferred paths
- Install required dependencies (`@spaceinvoices/js-sdk`, `@tanstack/react-query`)
- Copy essential files (SDK provider, utilities)
 - Copy generated Zod schemas when installed components depend on them
- Transform import paths to match your project structure
- Install npm dependencies for each component

### CLI Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize Space Invoices UI in your project |
| `add <component...>` | Add one or more components |
| `add --all` | Add all available components |
| `list` | List all available components |

### CLI Options

```bash
# Skip prompts and use defaults
npx @spaceinvoices/react-ui init --yes

# Overwrite existing files
npx @spaceinvoices/react-ui add customers --overwrite

# Specify working directory
npx @spaceinvoices/react-ui add invoices --cwd ./my-app
```

## Manual Setup (Alternative)

If you prefer manual control:

### 1. Install Dependencies

```bash
# Core requirements
npm install @spaceinvoices/js-sdk @tanstack/react-query

# For forms
npm install react-hook-form @hookform/resolvers zod

# UI components (choose one):
# Option A: Use shadcn/ui (recommended)
npx shadcn@latest init

# Option B: Use your existing component library
```

### 2. Clone This Repository

```bash
git clone https://github.com/space-invoices/react-ui.git
```

### 3. Copy What You Need

```bash
# Required: Core utilities and providers
cp -r react-ui/src/lib/ your-project/src/lib/
cp -r react-ui/src/providers/ your-project/src/providers/
cp -r react-ui/src/hooks/ your-project/src/hooks/

# Copy the components you need
cp -r react-ui/src/components/invoices/ your-project/src/components/space-invoices/
cp -r react-ui/src/components/customers/ your-project/src/components/space-invoices/
cp -r react-ui/src/components/table/ your-project/src/components/space-invoices/
# ... add more as needed

# Include generated schemas if you use form components
cp -r react-ui/src/generated/ your-project/src/generated/

# Optional: skip components/ui/ if you already use shadcn/ui or your own primitives
```

### 4. Update Import Paths

```bash
# Replace @/ui/ imports with your path alias
find your-project/src/components/space-invoices -type f -name "*.tsx" \
  -exec sed -i '' 's/@\/ui\//@\//g' {} +
```

### 5. Setup Providers

```tsx
// app.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { SDKProvider } from "./providers/sdk-provider";
import { EntitiesProvider } from "./providers/entities-provider";

const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SDKProvider
        apiUrl="https://eu.spaceinvoices.com"
        getAccessToken={() => localStorage.getItem("si_token")}
      >
        <EntitiesProvider>
          {/* Your app */}
        </EntitiesProvider>
      </SDKProvider>
    </QueryClientProvider>
  );
}
```

## What's Included

### Business Components (Copy These)

```
src/components/
├── invoices/           # Create, list, view invoices
├── customers/          # Customer management
├── items/              # Products/services catalog
├── payments/           # Payment tracking
├── taxes/              # Tax rate management
├── estimates/          # Quotes and estimates
├── credit-notes/       # Credit note handling
├── advance-invoices/   # Advance invoice handling
├── dashboard/          # Analytics charts
├── entities/           # Company/organization settings
├── documents/          # Shared document components
└── table/              # Generic data table infrastructure
```

### UI Primitives (Optional)

The `components/ui/` folder contains shadcn/ui-style components. You can:

- let the CLI install compatible primitives for you
- use shadcn/ui directly
- swap to your own component library after copying the feature components

```bash
npx shadcn@latest add button input form table dialog select
```

Or use your own component library and update imports in the copied components.

### Required Utilities

```
src/
├── providers/
│   ├── sdk-provider.tsx       # SDK context (required)
│   └── entities-provider.tsx  # Active entity context (required)
├── generated/
│   └── schemas/               # Generated Zod schemas used by form components
├── hooks/
│   └── *.ts                   # Shared hooks
└── lib/
    ├── utils.ts               # cn() utility
    └── translation.ts         # i18n helper
```

## Usage Examples

### Customer List

```tsx
import { CustomerListTable } from "@/components/space-invoices/customers/customer-list-table";
import { useEntities } from "@/providers/entities-provider";

export function CustomersPage() {
  const { activeEntity } = useEntities();

  return (
    <CustomerListTable
      entityId={activeEntity.id}
      onRowClick={(customer) => console.log("Selected:", customer)}
    />
  );
}
```

### Create Invoice Form

```tsx
import { CreateInvoiceForm } from "@/components/space-invoices/invoices/create";
import { useEntities } from "@/providers/entities-provider";

export function NewInvoicePage() {
  const { activeEntity } = useEntities();

  return (
    <CreateInvoiceForm
      entityId={activeEntity.id}
      onSuccess={(invoice) => {
        console.log("Created invoice:", invoice.number);
      }}
    />
  );
}
```

### Dashboard Charts

```tsx
import { RevenueTrendChart } from "@/components/space-invoices/dashboard/revenue-trend-chart";
import { InvoiceStatusChart } from "@/components/space-invoices/dashboard/invoice-status-chart";

export function DashboardPage() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <RevenueTrendChart entityId={activeEntity.id} />
      <InvoiceStatusChart entityId={activeEntity.id} />
    </div>
  );
}
```

## Customization

Since you own the code, customize freely:

### Modify Styles

```tsx
// In your copied component
<FormItem className="bg-gray-50 p-4 rounded-lg">
  <FormLabel className="text-blue-600 font-semibold">Customer Name</FormLabel>
  ...
</FormItem>
```

### Add Fields

```tsx
// Extend the schema
const createCustomerSchema = z.object({
  name: z.string().min(1),
  customField: z.string().optional(), // Your addition
});

// Add to the form
<FormField name="customField" ... />
```

### Add Translations

```typescript
// components/space-invoices/customers/locales/fr.ts
export default {
  "customer.name": "Nom du client",
  "customer.email": "Adresse e-mail",
};
```

## Architecture

### SDK Integration

Components use TanStack Query hooks wrapping the SDK:

```typescript
// customers.hooks.ts
export function useCreateCustomer() {
  const { sdk } = useSDK();
  return useMutation({
    mutationFn: (data) => sdk.customers.createCustomer({ data }),
  });
}
```

### Type Safety

All types come from `@spaceinvoices/js-sdk`:

```typescript
import type { Customer, Invoice } from "@spaceinvoices/js-sdk";
```

## Dependencies

```json
{
  "dependencies": {
    "@spaceinvoices/js-sdk": "^2.0.0",
    "@tanstack/react-query": "^5.0.0",
    "react": "^19.0.0",
    "react-hook-form": "^7.0.0",
    "@hookform/resolvers": "^5.0.0",
    "zod": "^3.0.0"
  }
}
```

## Documentation

- **[CONVENTIONS.md](./CONVENTIONS.md)** - Component patterns and architecture
- **[registry.json](./registry.json)** - Component registry with dependencies
- **[Space Invoices API Docs](https://docs.spaceinvoices.com)**
- **[shadcn/ui](https://ui.shadcn.com)**

## FAQ

**Q: Why copy-paste instead of npm install?**
A: Full ownership. Modify components freely without version conflicts or breaking changes.

**Q: Can I use Material UI / Chakra / other libraries?**
A: Yes. Update the imports in copied components to use your UI library instead of shadcn/ui.

**Q: Do I need the Space Invoices API?**
A: Yes. These components are built specifically for Space Invoices and won't work with other APIs.

**Q: How do I get updates?**
A: Check this repo for changes and manually merge what you need into your customized versions.

## License

MIT License - see [LICENSE](./LICENSE)