advance_cart_stepper

Bug Fixes

• iOS confirm/cancel in inline edit mode now apply correctly. Tapping ✓ or ✕ while the keyboard was open only dismissed the keyboard and left the quantity unchanged. The edit-action buttons are now wrapped in a TextFieldTapRegion (and guarded against focus-loss races) so the tap reaches confirm/cancel instead of being treated as "tap outside".
• Quantity tap target for inline edit is larger. Opening edit previously required hitting the digit glyphs; the whole middle area between −/+ is now tappable.

Features

• Inline edit mode for manual input. Tapping the quantity now turns the stepper into an editor in place: the number becomes a text field and the - / + buttons swap for cancel (✕) and confirm (✓) actions. Configure it via CartStepperManualInputConfig:
  • showEditActions (default true) — set to false to keep - / + visible while editing
  • cancelIcon / confirmIcon — icon overrides (default Icons.close / Icons.check)
  • editIconSize — size of the cancel/confirm icons, defaults to the stepper's normal icon size
  • cancelIconColor / confirmIconColor — default to the stepper's foreground color
  • cancelBackgroundColor / confirmBackgroundColor — circular button backgrounds, transparent by default
  • editBackgroundColor / editForegroundColor — recolor the whole pill (and the number) while editing; default to the stepper's normal colors
  • submitOnFocusLost (default true) — set to false so only the explicit confirm/cancel buttons leave edit mode

Bug Fixes

• Auto-collapse no longer fires while editing. The collapse timer was being restarted when manual input began, so the stepper would collapse mid-keystroke. It is now suppressed until editing ends.
• Collapsing while editing no longer strands the stepper in edit mode. Deleting the quantity (or any collapse to 0) left _isEditingManually set, so re-expanding showed an empty text field instead of the quantity. All collapse paths now exit edit mode.
• Tapping outside always leaves edit mode. Previously, with submitOnFocusLost: false, an outside tap did nothing and the stepper stayed stuck as a text field. It now commits or cancels depending on that flag.

Changes

• Removed the decorative box around the quantity that was drawn whenever enableManualInput was on. The number is still tappable, but renders plain — the switch to the inline editor is the affordance. Callers that relied on the tinted background + bottom border should supply their own wrapper.
• The cancel/confirm circles are now inset from the button tap target so they never overflow the stepper's rounded edge; the full tap area stays hittable.

Bug Fixes

• Fixed assertion error when maxQuantity equals minQuantity (e.g., products limited to exactly 1 unit)
  • Changed assertion from maxQuantity > minQuantity to maxQuantity >= minQuantity in both CartStepperController and _CartStepperCore
  • This allows the stepper to properly handle edge cases where maxQuantity == minQuantity, automatically disabling the increment button when at max

Bug Fixes

• Fixed setState() called during build exception in StepperButton that occurred when GestureDetector disposed its gesture recognizers during a rebuild, triggering onLongPressCancel / onTapCancel synchronously inside the build phase

Documentation

• Added Deep Dive: Throttle vs Debounce section explaining the two async execution strategies with flow diagrams and comparison table
• Added isLoading and Async Modes section documenting external vs internal loading state interactions and the debounce gotcha
• Added Best Practices & Common Patterns with 5 production-ready async configuration patterns
• Added Non-Blocking UI guide with strategy matrix showing which config combinations keep the stepper responsive
• Added Tips, Gotchas & Hidden Behaviors section covering 22+ non-obvious behaviors, edge cases, and practical tips for production use

Breaking Changes

• Split CartStepper into two widgets:
  • CartStepper<T> - Simple, ~20 parameters, synchronous only, supports generic num types
  • AsyncCartStepper<T> - Full-featured, ~35 parameters (organized into config objects), supports async operations, undo, streams, and more
• Flat parameters reorganized into config objects for better API clarity:
  • CartStepperAsyncBehavior - async settings (optimistic updates, debounce, throttle)
  • CartStepperLongPressConfig - long press behavior
  • CartStepperManualInputConfig - manual input settings
  • CartStepperCollapseConfig - auto-collapse behavior
  • CartStepperIconConfig - icon customization
• separateIcon renamed to collapsedBadgeIcon (via CartStepperIconConfig)
• QuantityFormatters now accept num instead of int
• ThemedCartStepper is now generic (ThemedCartStepper<T extends num>)
• CartStepperThemeData uses config objects instead of flat parameters

New Features

• Generic type support - CartStepper<double>(quantity: 1.5, ...) for decimal quantities
• Detailed quantity changed callback - onDetailedQuantityChanged: (newQty, oldQty, type) {}
• RTL / directionality support - textDirection: TextDirection.rtl
• Vertical layout - direction: CartStepperDirection.vertical
• Expand/collapse callbacks - onExpanded / onCollapsed
• Controller integration - controller: myController for external state management
• Reactive streams - quantityStream: myStream for stream-based updates
• Async validator - asyncValidator: (current, next) async => ...
• Expanded builder - expandedBuilder: (ctx, qty, inc, dec, loading) => ...
• Transition builder - animation: CartStepperAnimation(transitionBuilder: ...)
• Undo after delete - undoConfig: CartStepperUndoConfig(...) for undo support
• Group total callback - onTotalChanged: (total) {} for CartStepperGroup
• Group async support - onQuantityChangedAsync: (index, qty) async {} for groups
• Group selection mode - CartStepperSelectionMode.single
• Config object presets - CartStepperLongPressConfig.fast, CartStepperAsyncBehavior.optimistic, etc.

Improvements

• Refactored internal architecture with modular builder/facade/operations pattern
• Improved code organization and maintainability
• Enhanced analysis options for stricter linting
• Expanded test coverage
• Comprehensive example app with all feature demonstrations
• Added migration guide (MIGRATION.md)

Initial release of Advance Cart Stepper.

Features

• CartStepper Widget - Expandable cart quantity stepper with smooth animations
• Size Variants - Compact (32px), Normal (40px), and Large (48px) presets
• Add-to-Cart Styles - Circle icon, text buttons, and customizable configurations
• Async Support - Built-in loading indicators with 15+ SpinKit animations
• Optimistic Updates - Instant UI feedback with automatic error revert
• Debounce Mode - Batch rapid changes into single API calls
• Error Handling - onError callback and errorBuilder for inline error display
• Validation - Custom validators with rejection callbacks
• Long Press - Hold buttons for rapid increment/decrement
• Auto-Collapse - Collapse to badge view after inactivity
• Quantity Formatters - Built-in abbreviation (1.5k, 2M) and max indicators (99+)
• Manual Input - Tap quantity to type directly with keyboard
• Theming - CartStepperTheme for consistent styling across widgets
• Haptic Feedback - Optional haptics on button interactions
• Theme-Aware Colors - CartBadge uses theme colors by default

Components

• CartStepper - Main stepper widget
• CartStepperController - External state management with ChangeNotifier
• CartBadge - Display count badges on icons
• CartStepperGroup - Horizontal variant selection with generic type support
• CartProductTile - Complete product tile with integrated stepper
• ThemedCartStepper - Theme-aware stepper variant
• AnimatedCounter - Standalone animated number display
• StepperButton - Reusable button with long-press support

Configuration Classes

• CartStepperStyle - Colors, borders, typography customization
• CartStepperAnimation - Duration, curves, haptics configuration
• CartStepperLoadingConfig - Loading indicator type and behavior
• AddToCartButtonConfig - Initial button appearance and behavior
• CartStepperGroupItem - Generic item with required id for stable keys