@w3payments/react 1.3.0 → 1.5.0

package/README.md

@@ -260,7 +260,8 @@ Customize the widget appearance with props:
   subtitle="CHOOSE PAYMENT METHOD"
   logo="/your-logo.png"
   showAmount={false}  // Hide amount section
-  showHeader={false}  // Hide header with title/logo
+  // Logo/title displays automatically when provided
+  // Description displays when provided, independent of logo
   // ... other props
 />
 ```
@@ -284,33 +285,55 @@ import { W3PaymentWidget } from '@w3payments/react';
 #### Custom Themes
 
 ```tsx
-import type { W3Appearance } from '@w3payments/common';
+import type { W3Appearance } from '@w3payments/react';
 
 const customTheme: W3Appearance = {
   variables: {
     // Brand colors
-    primary: '#ff6b35',           // Orange brand color
-    background: '#f8f9fa',        // Light gray background
-    text: '#2d3748',             // Dark text
-    textSecondary: '#718096',     // Muted text
+    primary: '#ff6b35',                   // Orange brand color
+    
+    // Main layout backgrounds
+    mainBackground: '#ffffff',            // Outer container + footer background
+    innerBackground: '#f8f9fa',           // Inner container (amount/methods section)
+    cardBackground: '#ffffff',            // Payment method row background
+    
+    // Text colors (component-based)
+    primaryText: '#2d3748',               // Main text color (logo/headers)
+    secondaryText: '#718096',             // Secondary text (method descriptions, USD amounts)
+    descriptionText: '#718096',           // Widget description text
+    amountText: '#2d3748',                // Payment amount text
+    subtitleText: '#718096',              // "CHOOSE A PAYMENT METHOD" text
+    cardText: '#2d3748',                  // Payment method card text
+    cardSecondaryText: '#718096',         // Payment method card subtitle text
+    usdText: '#718096',                   // USD amount text color
+    footerText: '#718096',                // Footer text color
+    
+    // QR screen specific colors
+    qrAddressBackground: '#f8f9fa',       // QR address section background
+    qrAddressText: '#2d3748',             // QR address text color
+    qrInstructionsBackground: '#f8f9fa',   // QR instructions background
+    qrInstructionsText: '#718096',        // QR instructions text color
+    qrCardBackground: '#ffffff',          // QR network/token cards background
+    qrCardText: '#2d3748',                // QR network/token cards text
     
     // Status colors
-    success: '#38a169',          // Green
-    danger: '#e53e3e',           // Red
-    warning: '#dd6b20',          // Orange
-    border: '#e2e8f0',           // Light border
+    success: '#38a169',                   // Green
+    danger: '#e53e3e',                    // Red
+    warning: '#dd6b20',                   // Orange
+    borderColor: '#e2e8f0',               // Borders and dividers
+    info: '#3182ce',                      // Info background
     
     // Typography
     fontFamily: 'Inter, system-ui, sans-serif',
     fontSizeBase: '14px',
     fontSizeSmall: '12px',
-    fontSizeLarge: '28px',
-    fontWeightNormal: '500',
+    fontSizeLarge: '32px',
+    fontWeightNormal: '400',
     
     // Layout
-    spacingUnit: '6px',          // Increased spacing
-    borderRadius: '12px',        // More rounded
-    buttonRadius: '8px'          // Button radius
+    spacingUnit: '4px',                   // Base spacing unit
+    borderRadius: '8px',                  // Default border radius
+    buttonRadius: '6px'                   // Button border radius
   }
 };
 
@@ -322,15 +345,51 @@ const customTheme: W3Appearance = {
 ```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'
+    // Brand colors
+    primary: '#0085FF',                   // Blue accent
+    
+    // Dark layout backgrounds
+    mainBackground: '#14171D',            // Dark outer container + footer
+    innerBackground: '#1a1d24',           // Dark inner container
+    cardBackground: '#1f222a',            // Dark payment method cards
+    
+    // Light text on dark backgrounds
+    primaryText: '#C9CED8',               // Light headers/logo
+    secondaryText: '#8C99AD',             // Muted light text
+    descriptionText: '#8C99AD',           // Light description text
+    amountText: '#C9CED8',                // Light payment amount
+    subtitleText: '#8C99AD',              // Light subtitle
+    cardText: '#C9CED8',                  // Light card text
+    cardSecondaryText: '#8C99AD',         // Muted card text
+    usdText: '#8C99AD',                   // Light USD amounts
+    footerText: '#8C99AD',                // Light footer text
+    
+    // QR screen dark theme
+    qrAddressBackground: '#2B3039',       // Dark QR address section
+    qrAddressText: '#C9CED8',             // Light QR address text
+    qrInstructionsBackground: '#2B3039',   // Dark QR instructions
+    qrInstructionsText: '#8C99AD',        // Light QR instructions text
+    qrCardBackground: '#1f222a',          // Dark QR cards
+    qrCardText: '#C9CED8',                // Light QR card text
+    
+    // Bright status colors for dark theme
+    success: '#48bb78',                   // Bright green
+    danger: '#F23154',                    // Bright red
+    warning: '#ed8936',                   // Bright orange
+    borderColor: '#2B3039',               // Dark borders
+    info: '#1e3a5f',                      // Dark info background
+    
+    // Typography
+    fontFamily: 'SF Pro Display, system-ui, sans-serif',
+    fontSizeBase: '14px',
+    fontSizeSmall: '12px', 
+    fontSizeLarge: '32px',
+    fontWeightNormal: '400',
+    
+    // Layout
+    spacingUnit: '4px',
+    borderRadius: '8px',
+    buttonRadius: '6px'
   }
 };
 
@@ -404,23 +463,195 @@ 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)',
+    
+    // Map to your design system backgrounds
+    mainBackground: 'var(--surface-primary, #ffffff)',
+    innerBackground: 'var(--surface-secondary, #f8f9fa)',
+    cardBackground: 'var(--surface-primary, #ffffff)',
+    
+    // Map to your text color system
+    primaryText: 'var(--text-primary, #1a1a1a)',
+    secondaryText: 'var(--text-secondary, #6b7280)',
+    descriptionText: 'var(--text-muted, #6b7280)',
+    amountText: 'var(--text-primary, #1a1a1a)',
+    subtitleText: 'var(--text-secondary, #6b7280)',
+    cardText: 'var(--text-primary, #1a1a1a)',
+    cardSecondaryText: 'var(--text-muted, #6b7280)',
+    usdText: 'var(--text-secondary, #6b7280)',
+    footerText: 'var(--text-secondary, #6b7280)',
+    
+    // QR screen brand colors
+    qrAddressBackground: 'var(--surface-secondary, #f8f9fa)',
+    qrAddressText: 'var(--text-primary, #1a1a1a)',
+    qrInstructionsBackground: 'var(--surface-tertiary, #e5e7eb)',
+    qrInstructionsText: 'var(--text-secondary, #6b7280)',
+    qrCardBackground: 'var(--surface-primary, #ffffff)',
+    qrCardText: 'var(--text-primary, #1a1a1a)',
+    
+    // Status colors from design system
+    success: 'var(--status-success, #16a34a)',
+    danger: 'var(--status-error, #dc2626)',
+    warning: 'var(--status-warning, #ca8a04)',
+    borderColor: 'var(--border-default, #e5e7eb)',
+    info: 'var(--status-info, #3b82f6)',
     
     // Match your typography
     fontFamily: 'var(--font-family, Inter, sans-serif)',
     fontSizeBase: 'var(--text-sm, 14px)',
+    fontSizeSmall: 'var(--text-xs, 12px)',
+    fontSizeLarge: 'var(--text-2xl, 32px)',
+    fontWeightNormal: 'var(--font-normal, 400)',
     
     // Match your spacing scale  
     spacingUnit: 'var(--spacing-1, 4px)',
-    borderRadius: 'var(--radius-md, 8px)'
+    borderRadius: 'var(--radius-md, 8px)',
+    buttonRadius: 'var(--radius-sm, 6px)'
   }
 };
 
 <W3PaymentWidget appearance={brandTheme} />
 ```
 
+### Complete W3Appearance API Reference
+
+The W3Appearance API provides comprehensive theming control with component-based variable naming for precise styling.
+
+#### Background Colors
+```tsx
+{
+  // Main layout structure
+  mainBackground: string;        // Outer container + footer background
+  innerBackground: string;       // Inner container (amount/methods section)
+  cardBackground: string;        // Payment method row background
+  
+  // QR screen specific backgrounds
+  qrAddressBackground: string;   // QR address section background
+  qrInstructionsBackground: string; // QR instructions section background
+  qrCardBackground: string;      // QR network/token cards background
+}
+```
+
+#### Text Colors
+```tsx
+{
+  // Main content text colors
+  primaryText: string;           // Main text (logo, headers)
+  secondaryText: string;         // Secondary text (descriptions, labels)
+  descriptionText: string;       // Widget description text
+  amountText: string;           // Payment amount display
+  subtitleText: string;         // Section subtitles
+  
+  // Payment method cards
+  cardText: string;             // Payment method primary text
+  cardSecondaryText: string;    // Payment method subtitle text
+  
+  // Specific element colors
+  usdText: string;              // USD conversion amounts
+  footerText: string;           // Footer text
+  
+  // QR screen text colors
+  qrAddressText: string;        // QR address text
+  qrInstructionsText: string;   // QR instructions text
+  qrCardText: string;           // QR network/token cards text
+}
+```
+
+#### Status & Accent Colors
+```tsx
+{
+  primary: string;              // Brand/accent color
+  success: string;              // Success states (green)
+  danger: string;               // Error states (red) 
+  warning: string;              // Warning states (orange)
+  info: string;                 // Info backgrounds (blue)
+  borderColor: string;          // Borders and dividers
+}
+```
+
+#### Typography
+```tsx
+{
+  fontFamily: string;           // Primary font stack
+  fontSizeBase: string;         // Default text size (14px)
+  fontSizeSmall: string;        // Small text size (12px)
+  fontSizeLarge: string;        // Large text size (32px)
+  fontWeightNormal: string;     // Default font weight (400)
+}
+```
+
+#### Layout & Spacing
+```tsx
+{
+  spacingUnit: string;          // Base spacing unit (4px)
+  borderRadius: string;         // Default border radius (8px) 
+  buttonRadius: string;         // Button border radius (6px)
+}
+```
+
+#### Real-World Usage Examples
+
+**E-commerce Integration:**
+```tsx
+const ecommerceTheme: W3Appearance = {
+  variables: {
+    // Match your site's header/footer
+    mainBackground: '#ffffff',
+    footerText: '#6b7280',
+    
+    // Match product card styling
+    cardBackground: '#ffffff',
+    cardText: '#1f2937',
+    borderRadius: '12px',
+    
+    // Use your brand accent
+    primary: '#3b82f6',
+    amountText: '#059669', // Green for price
+  }
+};
+```
+
+**DeFi Application:**
+```tsx
+const defiTheme: W3Appearance = {
+  variables: {
+    // Dark crypto aesthetic
+    mainBackground: '#0f172a',
+    innerBackground: '#1e293b',
+    cardBackground: '#334155',
+    
+    // Bright accent for crypto
+    primary: '#00d4aa',
+    primaryText: '#f1f5f9',
+    amountText: '#00d4aa',
+    
+    // Crypto-friendly fonts
+    fontFamily: 'JetBrains Mono, monospace',
+    borderRadius: '4px', // Sharp edges
+  }
+};
+```
+
+**Banking Application:**
+```tsx
+const bankingTheme: W3Appearance = {
+  variables: {
+    // Conservative, trustworthy colors
+    mainBackground: '#fefefe',
+    primary: '#1e40af', // Deep blue
+    
+    // Clear hierarchy
+    primaryText: '#1f2937',
+    secondaryText: '#6b7280',
+    amountText: '#1f2937',
+    
+    // Professional typography
+    fontFamily: 'system-ui, sans-serif',
+    fontWeightNormal: '500',
+    borderRadius: '6px',
+  }
+};
+```
+
 ### Advanced CSS Customization
 
 For specific styling needs beyond the W3Appearance API:

package/dist/appearance.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+interface W3Appearance {
+    variables?: {
+        primary?: string;
+        mainBackground?: string;
+        innerBackground?: string;
+        cardBackground?: string;
+        primaryText?: string;
+        secondaryText?: string;
+        descriptionText?: string;
+        amountText?: string;
+        subtitleText?: string;
+        cardText?: string;
+        cardSecondaryText?: string;
+        usdText?: string;
+        footerText?: string;
+        qrAddressBackground?: string;
+        qrAddressText?: string;
+        qrInstructionsBackground?: string;
+        qrInstructionsText?: string;
+        qrCardBackground?: string;
+        qrCardText?: string;
+        danger?: string;
+        success?: string;
+        warning?: string;
+        borderColor?: string;
+        info?: 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 };
+export type { W3Appearance };
+//# 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,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE;QAEV,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QAGd,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;AAqCD,QAAA,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CA2BxE,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;AAC3B,YAAY,EAAE,YAAY,EAAE,CAAC"}