POC: new options for widget lit

[FranceBe]

✨ New Customization Options & Features for Alma Widgets (Lit)

🎯 Overview

This PR adds extensive new customization options to the Alma Widgets Lit implementation, focusing on visual flexibility, theming, and layout variants to better match merchant brand guidelines and integration contexts.

---

🎨 New Features

1. Color Scheme Options (colorScheme)

Allows merchants to customize the widget's primary color to match their brand or page theme.

Available options:

• orange (default) - Alma's signature orange
• light-gray - Subtle light gray theme
• gray - Medium gray theme
• dark-gray - Dark gray theme
• white - White theme (for dark backgrounds)
• black - Black theme

Usage:

widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
  colorScheme: 'black', // New option
})

Impact:

• Changes active button color
• Updates logo color (monochrome variants)
• Adjusts text contrast for accessibility
• Automatically adapts to light/dark backgrounds

---

2. Compact Mode (compactMode)

A condensed version of the widget with reduced size and minimalist styling.

Features:

• Smaller Alma logo (16x16 instead of 24x24)
• Reduced button size (~80% of original)
• No info text below buttons
• Maintains full functionality

Usage:

widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
  compactMode: true, // New option
})

Use cases:

• Product cards in listings
• Sidebar widgets
• Mobile-optimized layouts
• Space-constrained contexts

---

3. Inline Compact Mode (inlineCompact)

Shrinks the widget width to fit only the necessary content (no full-width expansion).

Behavior:

• Widget adapts to content width
• Perfect for inline placement
• Combines well with compactMode

Usage:

widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
  compactMode: true,
  inlineCompact: true, // New option - shrink width
})

Use cases:

• Inline with price display
• Small product cards
• Minimal footer integrations

---

4. Plan Button Style (planStyle)

Choose between traditional buttons or modern tab-style display.

Options:

• buttons (default) - Classic button design
• tabs - Tab-style navigation look

Usage:

widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
  planStyle: 'tabs', // New option
})

Benefits:

• Better visual hierarchy in tabs mode
• Cleaner look for modern designs
• Works in both PaymentPlans and Modal

---

5. Modal Panel Mode (panelMode)

Display the modal as a right-side sliding panel instead of centered overlay.

Features:

• Slides from right edge
• Full-height panel
• Better for mobile/tablet
• Maintains all modal functionality

Usage:

widgets.add(Alma.Widgets.Modal, {
  container: '#modal',
  purchaseAmount: 45000,
  panelMode: true, // New option - right slide panel
})

---

6. Bottom Sheet Mode (bottomSheet)

On desktop, display modal as a bottom sheet (drawer from bottom).

Features:

• Slides up from bottom
• Adapts height to content
• Mobile-first UX on desktop
• Full modal functionality

Usage:

widgets.add(Alma.Widgets.Modal, {
  container: '#modal',
  purchaseAmount: 45000,
  bottomSheet: true, // New option - bottom drawer
})

Note: Mobile always uses bottom sheet by default (< 800px width).

---

📦 Widget Options Summary

Payment Plans Widget

Option	Type	Default	Description
colorScheme	string	'orange'	Primary color theme
compactMode	boolean	false	Compact UI variant
inlineCompact	boolean	false	Shrink width to content
planStyle	'buttons' | 'tabs'	'buttons'	Button vs tab style
monochrome	boolean	false	Black & white mode
hideBorder	boolean	false	Remove outer border

Modal Widget

Option	Type	Default	Description
panelMode	boolean	false	Right-side slide panel
bottomSheet	boolean	false	Bottom drawer (desktop)
planStyle	'buttons' | 'tabs'	'buttons'	Button vs tab style

Schedule Widget

New widget available as a "standalone" widget to display uniquely the schedule, with or without a plan selector. With customizable options.

Option	Type	Default	Description
small	boolean	false	80% size variant
monochrome	boolean	false	Black/gray theme
hideBorder	boolean	false	Borderless
light	boolean	false	Minimal UI mode

---

📚 Documentation Updates

• ✅ README updated with all new options
• ✅ Examples in examples/ folder
• ✅ Playground interactive demo
• ✅ TypeScript types updated
• ✅ JSDoc comments for all new props

---

🎬 Demo

Visit examples/playground.html to test all new options interactively:

• Try different color schemes
• Toggle compact modes
• Switch between button and tab styles
• Test modal panel/bottom-sheet variants
• See disabled plans in action

---

🔄 Migration Guide

All new options are opt-in and backward compatible. Existing integrations continue to work without changes.

To use new features:

// Before (still works)
widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
})

// After (with new options)
widgets.add(Alma.Widgets.PaymentPlans, {
  container: '#widget',
  purchaseAmount: 45000,
  colorScheme: 'black',     // NEW
  compactMode: true,        // NEW
  planStyle: 'tabs',        // NEW
})

---

📊 Before/After Comparison

Color Customization

Before: Only orange or monochrome (black/white)
After: 6 color schemes + better contrast handling

Layout Variants

Before: Single full-width layout
After: Compact, inline-compact, tab-style variants

Modal Positioning

Before: Centered overlay only
After: Centered, right-panel, or bottom-sheet

✅ Checklist

• All new features implemented
• Tests passing (117/117)
• Documentation updated
• Playground examples added
• Backward compatibility maintained
• TypeScript types updated
• Accessibility verified
• Design tokens implemented
• Code reviewed and optimized