npm package: @finework/ui
Description: Generic UI component library extracted from OrdinaGO - Reusable components, layouts, and utilities for Next.js projects
Author: Finework
Latest version: 1.0.0

# @finework/ui

Una libreria UI generica e riutilizzabile estratta da OrdinaGO. Include componenti React, layout, modali, utilities e sistema di form completamente configurabili per progetti Next.js e React.

## 🎯 Caratteristiche

- **Componenti UI Generici**: Set completo di componenti basati su shadcn/ui e Radix UI
- **Sistema di Modali**: Context-based modal system con supporto per modali slide-in
- **Layout Components**: BaseLayout con action bar configurabile
- **Data Management**: Componente generico per CRUD operations
- **Form System**: Integrazione completa con react-hook-form e Zod
- **Utilities**: Helper functions per API calls, date formatting, graphics
- **TypeScript**: Completamente tipizzato
- **Tailwind CSS**: Styling con Tailwind e supporto dark mode
- **Zero Business Logic**: Tutta la logica di business è separata, solo UI pura

## 📦 Installazione

```bash
npm install @finework/ui
# oppure
yarn add @finework/ui
# oppure
pnpm add @finework/ui
```

## 🚀 Quick Start

### 1. Configura Tailwind CSS

Aggiungi il contenuto di `@finework/ui/styles` al tuo file CSS globale e configura `tailwind.config.ts` con i colori della libreria (vedi `tailwind.config.ts` in questo repo).

### 2. Setup Providers

```tsx
// app/layout.tsx o _app.tsx
import { AppProviders } from '@finework/ui';
import '@finework/ui/styles';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AppProviders enableModal={true}>
          {children}
        </AppProviders>
      </body>
    </html>
  );
}
```

### 3. Usa i Componenti

```tsx
import { Button, Card, Input, BaseLayout, useModal } from '@finework/ui';

export default function MyPage() {
  const { openModal } = useModal();
  
  return (
    <BaseLayout 
      title="My Page"
      extraActions={[
        { id: '1', label: 'New', onClick: () => openModal(<div>Modal</div>) }
      ]}
    >
      <Card>
        <CardHeader>
          <CardTitle>Hello World</CardTitle>
        </CardHeader>
        <CardContent>
          <Button>Click me</Button>
        </CardContent>
      </Card>
    </BaseLayout>
  );
}
```

## 📚 Componenti Principali

### UI Components
- `Button`, `Input`, `Card`, `Label`, `Alert`, `Skeleton`, `Textarea`, `Badge`, `Form`, `Dialog`, `Separator`, `Avatar`

### Layout & Modals
- `BaseLayout` - Layout con action bar configurabile
- `useModal` - Hook per gestione modali
- `Modal`, `ModalWrapper` - Sistema modali
- `DataManagementModal` - CRUD generico

### Utilities
- `callApi()` - Helper per API calls
- `formatDate()`, `formatDateReadable()` - Formattazione date
- `stringToColor()`, `getInitials()` - Graphics utilities
- `cn()` - Merge classi Tailwind

## 🎨 Theming

La libreria supporta dark mode tramite CSS variables. I colori sono definiti in `@finework/ui/styles` e possono essere personalizzati sovrascrivendo le variabili CSS.

## 📖 Types

```tsx
import type { 
  ApiResponse, 
  NamedEntity, 
  ExtraAction,
  BaseComponentProps 
} from '@finework/ui/types';
```

## 🔧 Build

```bash
# Build the library
npm run build

# Watch mode
npm run dev

# Type check
npm run type-check
```

## 📝 Esempi

Vedi il progetto demo in `../finework-ui-demo` per esempi completi di utilizzo.

## 🤝 Contribuire

Questa libreria è stata estratta da OrdinaGO per essere riutilizzata in altri progetti. Per aggiungere nuovi componenti:

1. Crea il componente in `src/components/`
2. Assicurati che non contenga logica di business specifica
3. Esporta il componente dall'index appropriato
4. Aggiungi la documentazione

## 📄 Licenza

MIT

## 🏗️ Architettura

```
src/
├── components/        # Componenti React
│   ├── ui/           # Componenti UI base (shadcn)
│   ├── layout/       # Layout components
│   ├── modals/       # Modal system
│   └── forms/        # Form components
├── hooks/            # Custom hooks
├── lib/              # Utilities e helpers
├── types/            # TypeScript types
├── providers/        # Context providers
└── styles.css        # Global styles
```

## ⚠️ Note

- Questa libreria è **agnostica** rispetto alla logica di business
- Tutti i componenti sono **completamente configurabili**
- Richiede **React 18+** e **Next.js 13+** (App Router)
- Usa **Tailwind CSS** per lo styling
- Le chiamate API devono essere gestite dal progetto che usa la libreria

## 🚀 Pubblicazione

Per pubblicare su npm:

```bash
npm run build
npm login
npm publish --access public
```

Vedi `PUBBLICAZIONE_NPM.md` per dettagli completi.