friday-widgets/README.md

Professional embeddable accounting widgets for vertical SaaS platforms. Layer Financial-inspired design with comprehensive financial reporting capabilities.

# Friday Widgets

Professional embeddable accounting widgets for vertical SaaS platforms. Built with Web Components and TypeScript with modern design excellence.

[![npm version](https://badge.fury.io/js/%40friday%2Fwidgets.svg)](https://badge.fury.io/js/%40friday%2Fwidgets)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Lit](https://img.shields.io/badge/Lit-3.1-orange.svg)](https://lit.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

✨ **Framework Agnostic** - Works with React, Vue, Angular, or vanilla JavaScript  
🎨 **Professional Design** - Modern design system with Inter font and sophisticated styling  
🔒 **Shadow DOM** - Complete CSS isolation prevents conflicts  
💪 **TypeScript** - Full type safety and excellent developer experience  
🏢 **Multi-tenant B2B2B** - Partner → Business → User architecture  
🌍 **EU/UK Compliance** - IBAN validation, VAT, SEPA support  

## Installation

```bash
npm install @friday/widgets
```

## Quick Start

### 1. Configure the Provider

```javascript
import { FridayProvider } from '@friday/widgets';

// Configure once globally
FridayProvider.configure({
  businessId: 'bus_your_business_id',
  businessAccessToken: 'pk_your_access_token',
  environment: 'sandbox', // or 'production'
  theme: {
    primaryColor: '#2563eb',
    mode: 'light' // 'light', 'dark', or 'auto'
  }
});
```

### 2. Use Widgets

#### Import All Widgets
```javascript
import '@friday/widgets';

// Now use in HTML
<friday-invoice-widget show-demo="true"></friday-invoice-widget>
<friday-cash-flow-statement-widget show-demo="true"></friday-cash-flow-statement-widget>
```

#### Import Individual Widgets
```javascript
import '@friday/widgets/invoice';
import '@friday/widgets/cash-flow-statement';

// Use in HTML
<friday-invoice-widget show-demo="true"></friday-invoice-widget>
<friday-cash-flow-statement-widget show-demo="true"></friday-cash-flow-statement-widget>
```

### 3. Framework Integration

#### React
```jsx
import '@friday/widgets';

function App() {
  useEffect(() => {
    FridayProvider.configure({
      businessId: 'bus_demo',
      businessAccessToken: 'pk_test_key',
      environment: 'sandbox'
    });
  }, []);

  return (
    <div>
      <friday-invoice-widget show-demo="true" />
      <friday-cash-flow-statement-widget show-demo="true" />
    </div>
  );
}
```

#### Vue
```vue
<template>
  <div>
    <friday-invoice-widget show-demo="true" />
    <friday-cash-flow-statement-widget show-demo="true" />
  </div>
</template>

<script>
import '@friday/widgets';
import { FridayProvider } from '@friday/widgets';

export default {
  mounted() {
    FridayProvider.configure({
      businessId: 'bus_demo',
      businessAccessToken: 'pk_test_key',
      environment: 'sandbox'
    });
  }
}
</script>
```

## Available Widgets

### Core Accounting Widgets
- **`friday-invoice-widget`** - Invoice management and creation
- **`friday-link-accounts-widget`** - Bank account connection flow  
- **`friday-linked-accounts-widget`** - Connected account management
- **`friday-bank-transactions-widget`** - Transaction categorization and approval

### Financial Reporting Widgets
- **`friday-pnl-cards-widget`** - P&L summary cards with mini charts
- **`friday-pnl-chart-widget`** - 12-month P&L trend visualization
- **`friday-pnl-table-widget`** - Expandable hierarchical P&L table
- **`friday-pnl-breakdown-widget`** - Interactive P&L pie charts
- **`friday-cash-flow-statement-widget`** - Cash flow statement with indirect method
- **`friday-balance-sheet-widget`** - Professional balance sheet reporting
- **`friday-chart-of-accounts-widget`** - Chart of accounts management

### Coming Soon
- **`friday-payment-widget`** - Payment processing forms
- **`friday-dashboard-widget`** - Key metrics overview
- **`friday-customer-widget`** - Customer management

## Widget Configuration

### Global Configuration (Recommended)
```javascript
FridayProvider.configure({
  businessId: 'bus_your_business_id',
  businessAccessToken: 'pk_your_access_token',
  environment: 'sandbox', // 'sandbox' | 'production'
  theme: {
    primaryColor: '#2563eb',
    mode: 'light' // 'light' | 'dark' | 'auto'
  }
});
```

### Individual Widget Properties
```html
<!-- Cash Flow Statement -->
<friday-cash-flow-statement-widget 
  show-demo="true"
  default-date-picker-mode="monthPicker"
  allowed-date-picker-modes="['monthPicker', 'quarterPicker', 'yearPicker']"
  label="Select Period"
  start-date="2024-01-01"
  end-date="2024-12-31">
</friday-cash-flow-statement-widget>

<!-- P&L Table -->
<friday-pnl-table-widget 
  show-demo="true"
  lock-expanded="false">
</friday-pnl-table-widget>

<!-- P&L Cards -->
<friday-pnl-cards-widget 
  show-demo="true"
  actionable="true"
  variants='{"size": "lg"}'>
</friday-pnl-cards-widget>
```

## Event System

All widgets emit custom events that you can listen to:

```javascript
// Cash Flow Statement events
document.addEventListener('cash-flow-loaded', (e) => {
  console.log('Cash flow data loaded:', e.detail);
});

document.addEventListener('date-picker-mode-changed', (e) => {
  console.log('Date mode changed:', e.detail);
});

// P&L events
document.addEventListener('pnl-table-loaded', (e) => {
  console.log('P&L table loaded:', e.detail);
});

document.addEventListener('pnl-cards-loaded', (e) => {
  console.log('P&L cards loaded:', e.detail);
});

// Invoice events
document.addEventListener('friday-invoice-selected', (e) => {
  console.log('Invoice selected:', e.detail);
});

document.addEventListener('friday-payment-recorded', (e) => {
  console.log('Payment recorded:', e.detail);
});

// Error handling
document.addEventListener('friday-error', (e) => {
  console.error('Widget error:', e.detail);
});
```

## Styling & Theming

Friday Widgets use a professional design system with CSS custom properties:

```css
/* Friday uses these CSS variables for theming */
:root {
  /* Colors (HSL-based system) */
  --color-primary: hsl(220, 91%, 56%);
  --color-success: hsl(142, 71%, 45%);
  --color-warning: hsl(38, 92%, 50%);
  --color-error: hsl(0, 84%, 60%);
  
  /* Typography */
  --font-family-primary: 'InterVariable', 'Inter', sans-serif;
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
  
  /* Spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 0.75rem;
  --spacing-lg: 1rem;
  --spacing-xl: 1.5rem;
  --spacing-2xl: 2rem;
}
```

### CSS Class Prefixing
All components use `Friday__` prefixed classes to prevent conflicts:
- `.Friday__component` - Main component wrapper
- `.Friday__header` - Component headers
- `.Friday__table` - Data tables
- `.Friday__button` - Interactive buttons
- `.Friday__card` - Card components

## Browser Compatibility

- ✅ Chrome 63+
- ✅ Firefox 67+
- ✅ Safari 13.1+
- ✅ Edge 79+

Requires support for:
- Web Components (Custom Elements v1)
- Shadow DOM v1
- ES2020 features
- CSS Custom Properties

## TypeScript Support

Full TypeScript definitions included:

```typescript
import { FridayProvider, InvoiceWidget, CashFlowStatementWidget } from '@friday/widgets';
import type { 
  ProviderConfig, 
  CashFlowData, 
  InvoiceData,
  BankTransaction 
} from '@friday/widgets';

// Type-safe configuration
const config: ProviderConfig = {
  businessId: 'bus_demo',
  businessAccessToken: 'pk_test',
  environment: 'sandbox',
  theme: {
    primaryColor: '#2563eb',
    mode: 'light'
  }
};

FridayProvider.configure(config);
```

## Development & Testing

```bash
# Install dependencies
npm install

# Development build with watching
npm run build:watch

# Production build
npm run build

# Type checking
npm run type-check

# Run tests
npm test

# Clean dist folder
npm clean
```

## Architecture

Friday Widgets follow modern web component patterns:

- **Provider Configuration**: Global configuration approach for easy setup
- **Design System**: Professional styling with Friday branding
- **Component Architecture**: Modular component structure and props
- **Event System**: Comprehensive event naming and data structures
- **CSS Architecture**: Friday__ prefixed classes for style isolation

## License

MIT © Friday Accounting

## Support

- **GitHub Issues**: [Report bugs and feature requests](https://github.com/friday-ai/friday-widgets/issues)
- **Documentation**: [Full documentation](https://github.com/friday-ai/friday-widgets#readme)
- **Examples**: Check the `/examples` directory in the package

---

Built with ❤️ by the Friday team for modern accounting integrations.