@w3payments/react 1.2.1 → 1.4.0

package/README.md

@@ -248,28 +248,208 @@ Seamless payments across Bitcoin, Ethereum, Solana, Polygon with automatic bridg
 ### Crypto Offramping
 Direct crypto-to-fiat conversions with bank account deposits.
 
-## Styling
+## Customization
 
-Override default colors with CSS variables:
+### Widget Branding
+
+Customize the widget appearance with props:
+
+```tsx
+<W3PaymentWidget
+  title="Your Brand Name"
+  subtitle="CHOOSE PAYMENT METHOD"
+  logo="/your-logo.png"
+  showAmount={false}  // Hide amount section
+  showHeader={false}  // Hide header with title/logo
+  // ... other props
+/>
+```
+
+### Theme Customization
+
+Use the **W3Appearance API** for consistent theming across all components:
+
+#### Built-in Themes
+
+```tsx
+import { W3PaymentWidget } from '@w3payments/react';
+
+// Default light theme
+<W3PaymentWidget theme="default" />
+
+// Dark theme
+<W3PaymentWidget theme="night" />
+```
+
+#### Custom Themes
+
+```tsx
+import type { W3Appearance } from '@w3payments/common';
+
+const customTheme: W3Appearance = {
+  variables: {
+    // Brand colors
+    primary: '#ff6b35',           // Orange brand color
+    background: '#f8f9fa',        // Light gray background
+    text: '#2d3748',             // Dark text
+    textSecondary: '#718096',     // Muted text
+    
+    // Status colors
+    success: '#38a169',          // Green
+    danger: '#e53e3e',           // Red
+    warning: '#dd6b20',          // Orange
+    border: '#e2e8f0',           // Light border
+    
+    // Typography
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSizeBase: '14px',
+    fontSizeSmall: '12px',
+    fontSizeLarge: '28px',
+    fontWeightNormal: '500',
+    
+    // Layout
+    spacingUnit: '6px',          // Increased spacing
+    borderRadius: '12px',        // More rounded
+    buttonRadius: '8px'          // Button radius
+  }
+};
+
+<W3PaymentWidget appearance={customTheme} />
+```
+
+#### Dark Theme Example
+
+```tsx
+const darkTheme: W3Appearance = {
+  variables: {
+    primary: '#0085FF',          // Blue accent
+    background: '#1a202c',       // Dark background
+    text: '#f7fafc',            // Light text
+    textSecondary: '#a0aec0',   // Muted light text
+    success: '#48bb78',         // Bright green
+    danger: '#f56565',          // Bright red
+    warning: '#ed8936',         // Bright orange
+    border: '#4a5568',          // Dark border
+    fontFamily: 'SF Pro Display, system-ui, sans-serif'
+  }
+};
+
+<W3PaymentWidget appearance={darkTheme} />
+```
+
+#### Theming with Context
+
+Apply themes globally using the provider:
+
+```tsx
+<W3PaymentsProvider 
+  endpoint="http://localhost:3001/api/payments"
+  environment="sandbox"
+  appearance={customTheme}  // Applied to all widgets
+>
+  <W3PaymentWidget amount="100.00" />
+  <W3PaymentWidget amount="50.00" />  {/* Both use customTheme */}
+</W3PaymentsProvider>
+```
+
+### Advanced Theming
+
+#### Responsive Themes
+
+```tsx
+const useResponsiveTheme = () => {
+  const [theme, setTheme] = useState<W3Appearance>({
+    variables: {
+      primary: '#2563eb',
+      spacingUnit: window.innerWidth < 768 ? '3px' : '4px',
+      fontSizeBase: window.innerWidth < 768 ? '13px' : '14px',
+      borderRadius: window.innerWidth < 768 ? '6px' : '8px'
+    }
+  });
+  
+  useEffect(() => {
+    const handleResize = () => {
+      setTheme(prev => ({
+        variables: {
+          ...prev.variables,
+          spacingUnit: window.innerWidth < 768 ? '3px' : '4px',
+          fontSizeBase: window.innerWidth < 768 ? '13px' : '14px',
+          borderRadius: window.innerWidth < 768 ? '6px' : '8px'
+        }
+      }));
+    };
+    
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, []);
+  
+  return theme;
+};
+
+// Usage
+function PaymentPage() {
+  const responsiveTheme = useResponsiveTheme();
+  
+  return (
+    <W3PaymentWidget appearance={responsiveTheme} />
+  );
+}
+```
+
+#### Brand Integration
+
+```tsx
+// Extract colors from your design system
+const brandTheme: W3Appearance = {
+  variables: {
+    // Use your brand colors
+    primary: 'var(--brand-primary, #2563eb)',
+    background: 'var(--surface-primary, #ffffff)',
+    text: 'var(--text-primary, #1a1a1a)',
+    textSecondary: 'var(--text-secondary, #6b7280)',
+    
+    // Match your typography
+    fontFamily: 'var(--font-family, Inter, sans-serif)',
+    fontSizeBase: 'var(--text-sm, 14px)',
+    
+    // Match your spacing scale  
+    spacingUnit: 'var(--spacing-1, 4px)',
+    borderRadius: 'var(--radius-md, 8px)'
+  }
+};
+
+<W3PaymentWidget appearance={brandTheme} />
+```
+
+### Advanced CSS Customization
+
+For specific styling needs beyond the W3Appearance API:
 
 ```css
-.w3-widget {
-  --color-primary: #6366f1;
-  --color-background: #ffffff;
-  --color-border: #e5e7eb;
-  --color-text: #111827;
-  --color-text-muted: #6b7280;
+/* Target widget container */
+[data-w3-payment-widget] {
+  /* Widget-level customization */
+  min-height: 500px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+/* Customize payment buttons */
+[data-w3-payment-widget] button {
+  transition: all 0.2s ease;
 }
 
-/* Dark theme */
-[data-theme="dark"] .w3-widget {
-  --color-primary: #818cf8;
-  --color-background: #1f2937;
-  --color-border: #374151;
-  --color-text: #f9fafb;
+[data-w3-payment-widget] button:hover {
+  transform: translateY(-1px);
+}
+
+/* Amount input styling */
+[data-w3-payment-widget] input[type="number"] {
+  letter-spacing: 0.05em;
 }
 ```
 
+**Note:** The W3Appearance API handles all standard theming needs. CSS overrides should only be used for specific animations or layout adjustments not covered by the design system.
+
 ## How It Works
 
 1. **Payment Initiation**: User selects amount and payment method

package/dist/appearance.d.ts

@@ -0,0 +1,30 @@
+/**
+ * W3 Payment Widget Appearance Configuration
+ *
+ * Following Stripe's appearance API pattern for simple but complete theming.
+ * This file belongs in the React package as it's UI-specific.
+ */
+export interface W3Appearance {
+    variables?: {
+        primary?: string;
+        background?: string;
+        text?: string;
+        textSecondary?: string;
+        danger?: string;
+        success?: string;
+        warning?: string;
+        border?: string;
+        fontFamily?: string;
+        fontSizeBase?: string;
+        fontSizeSmall?: string;
+        fontSizeLarge?: string;
+        fontWeightNormal?: string;
+        spacingUnit?: string;
+        borderRadius?: string;
+        buttonRadius?: string;
+    };
+}
+declare const BUILT_IN_THEMES: Record<string, Required<W3Appearance['variables']>>;
+export declare const getThemeVariables: (themeName?: string, appearance?: W3Appearance) => Record<string, string>;
+export { BUILT_IN_THEMES };
+//# sourceMappingURL=appearance.d.ts.map

package/dist/appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE;QAEV,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAGhB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAG1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAqBD,QAAA,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAWxE,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,YAAW,MAAkB,EAC7B,aAAa,YAAY,KACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAUvB,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,CAAC"}