friday-widgets

v1.0.1

Published

7 months ago

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.

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

npm install @friday/widgets

Quick Start

1. Configure the Provider

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

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

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

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

<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)

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

<!-- 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:

// 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:

/* 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:

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

# 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

Support

GitHub Issues: Report bugs and feature requests
Documentation: Full documentation
Examples: Check the /examples directory in the package

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