morphing_sheet 0.6.2

A production-ready Flutter package for contextual morphing containers — supporting both card carousel snapping and Instamart-style overlay card transitions.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.6.2 - 2026-03-05

Added

• MorphingListBuilder (High-Level API) — A new "all-in-one" builder that abstracts away controller management, overlay wiring, and gesture handling:
  • MorphingListBuilder<T> provides a declarative API similar to ListView.builder.
  • Automatically manages OverlayMorphController lifecycle.
  • Supports grid mode with responsive column logic (Phone: 2, Tablet: 3, Desktop: 4).
  • Injects MorphingSource and MorphShared (hero tags) automatically.
• Premium Spatial UI/UX — Advanced interactions for a flagship-grade feel:
  • Curved Thumbnail Navigation: A center-locked, scrollable thumbnail bar in the overlay that curves upward at the center using an exponential mathematical curve.
  • 3D Perspective Tilt: Cards subtly tilt in 3D space during drag gestures.
  • Premium Lift Animations: Uses Curves.easeOutBack and 3D scaling (0.96 → 1.0) for a "popping" entrance.
  • Parallax Content: Content inside cards shifts slightly while swiping, creating a 3D depth illusion.
• New Atomic Components:
  • MorphListView and MorphGridView for standard layout rendering.
  • MorphPreviewCarousel for horizontal card swiping logic.

Changed

• Overlay UX: Replaced simple dot indicators with the premium thumbnail bar.
• Performance: Added RepaintBoundary isolation for the overlay card and thumbnail layers to ensure 60/120 FPS.

Migration from 0.5.x

• Developers can now replace manual MorphingSource + MorphingOverlay code with a single MorphingListBuilder for a ~75% reduction in boilerplate.

0.5.0 - 2026-03-03

Changed (Breaking)

• Overlay Rect Mode upgraded to Overlay Carousel Mode — the overlay now integrates a full horizontal card carousel between appear and fullscreen phases:
  • OverlayMorphController now uses two AnimationControllers: one for appear/disappear (origin → card center), one for expand/collapse (card → fullscreen). Requires TickerProviderStateMixin (not SingleTickerProviderStateMixin).
  • OverlayMorphState replaces single progress field with overlayProgress + expandProgress, adds currentIndex, itemCount, horizontalDragOffset, and cardRect.
  • OverlayPhase expanded: idle → appearing → cardMode → expanding → fullscreen → collapsing → cardMode → disappearing → idle.
  • MorphingOverlay<T> now requires items: List<T> to render the horizontal carousel. Renders active + adjacent cards with scale, opacity, and direction-locked horizontal swiping.
  • MorphingSource<T> now requires itemIndex: int for carousel starting position.
  • OverlayGestureLayer upgraded to direction-locking pan gestures (horizontal → carousel, vertical up → expand, vertical down → dismiss).
  • OverlayMorphController.selectItem now takes itemIndex parameter.
  • New controller methods: setIndex(int), collapse(), onHorizontalDragUpdate(), onHorizontalDragEnd().
  • New controller getters: overlayProgress, expandProgress, currentIndex, itemCount, cardRect, horizontalDragOffset.
• RectMorphTween extended with overlay carousel helpers: computeCardRect, overlayScrimOpacity, overlayBlur, overlayBackgroundScale, adjacentCardOpacity, adjacentCardScale.

Migration from 0.4.x

• Replace OverlayMorphState.progress with overlayProgress + expandProgress.
• Replace OverlayPhase.expanding/collapsing with new multi-phase state machine (add handling for appearing, cardMode, disappearing).
• Add items: [...] parameter to MorphingOverlay.
• Add itemIndex: index parameter to MorphingSource.
• Change SingleTickerProviderStateMixin to TickerProviderStateMixin in host widget.

Unchanged

• All v0.3.0 card carousel APIs remain fully intact.
• package:morphing_sheet/morphing_card_carousel.dart barrel export unchanged.

0.4.0 - 2026-03-03

Added

• Overlay Rect Mode — Instamart-style contextual morph where a tapped grid/list item expands from its exact on-screen position into a floating container, then into fullscreen detail:
  • OverlayMorphController — single AnimationController driving rect-based morph progress with selectItem(item, originRect:), dismiss(), expand(), and gesture callbacks
  • OverlayMorphState — immutable state snapshot: State = f(progress, selectedItem, originRect) with computed currentRect via Rect.lerp
  • OverlayPhase state machine: idle → expanding → fullscreen → collapsing → idle
  • MorphingOverlay<T> — main overlay container widget with scrim, blur, and Positioned.fromRect card rendering
  • MorphingSource<T> — tap-capture wrapper that reads RenderBox global position and triggers selectItem
  • OverlayGestureLayer — vertical drag handling for expand/collapse/flick-dismiss
  • RectMorphTween — pure-function interpolation helpers for rect, position, size, radius, elevation (peak-and-drop), scrim opacity, blur, background scale, and content crossfade
• New barrel export: package:morphing_sheet/morphing_overlay.dart
• Overlay rect mode example app with product grid, contextual morph, and fullscreen detail
• Demo hub with navigation to both Card Carousel and Overlay Rect modes

Unchanged

• All v0.3.0 card carousel APIs remain fully intact (MorphingCardCarousel<T>, CardCarouselController, CardMorphTween, etc.)
• package:morphing_sheet/morphing_card_carousel.dart barrel export unchanged

0.3.0 - 2026-03-03

Added

• Morphing Card Carousel — a centered, card-based, swipe-driven fullscreen-morph interaction system:
  • MorphingCardCarousel<T> main widget with generic item support
  • CardCarouselController — single AnimationController driving vertical morph, radius, elevation, background blur, and thumbnail opacity
  • CardMorphTween — pure-function interpolation helpers (morphHeight, morphWidth, morphRadius, morphElevation, morphBackgroundOpacity, morphBackgroundBlur, thumbnailOpacity)
  • CarouselScrollPhysics — custom velocity-aware snap physics (no default PageView physics)
  • CarouselSnapResolver — deterministic horizontal index resolution from velocity + displacement
  • CardGestureLayer — direction-locking gesture disambiguation (horizontal vs vertical)
  • CardStackLayer — positioned card rendering with active/adjacent transforms
  • ThumbnailSelectorBar — horizontally scrollable circular thumbnail strip with auto-scroll
  • BackgroundLayer — scale, blur, and barrier driven by progress
  • CardPhase state machine: collapsedCard → transitioningToFull → fullscreen → transitioningToCard
  • CardCarouselState — immutable state snapshot: State = f(verticalProgress, currentIndex)
  • CardItem<T> — stable-identity data wrapper
• Card carousel example app with Swiggy Instamart-style product cards, detail morph, and persistent cart bar

Changed

• Complete architectural rebuild from bottom-sheet paradigm to centered card carousel paradigm
• Package now exports via morphing_card_carousel.dart barrel file
• No implicit animation widgets — all visuals driven by raw Opacity, Transform, SizedBox
• Horizontal and vertical gestures are direction-locked after 16px threshold
• Index changes only when verticalProgress == 0.0

Removed

• All v0.1.x/v0.2.x sheet-based APIs (MorphingSheet, SheetController, SheetConfig, SheetScaffold, etc.)
• DraggableScrollableSheet-based patterns
• Default PageView snapping

Migration from 0.2.x

This is a breaking change. Replace MorphingSheet / MorphingSheet.listDriven<T>() with MorphingCardCarousel<T>(). Replace SheetController with CardCarouselController.

0.2.1

• Added pub.dev badges to README
• Documentation improvements

0.2.0 - 2026-03-03

Added

• List-driven mode via MorphingSheet.listDriven<T>() — context-aware, item-selection-based sheet with three content layers:
  • DynamicListLayer — lazy ListView.builder for collapsed state (supports 200+ items at 60fps)
  • PreviewLayer — selected item preview at half-expanded state
  • DetailLayer — fullscreen scrollable detail at expanded state with scroll-to-drag handoff
• SheetItem<T> model — lightweight value object wrapping user data for list-driven mode.
• ItemMorphTween — pure-function interpolation helpers for item-to-sheet morph transitions (morphRect, morphRadius, morphElevation, listOpacity, previewOpacity, detailOpacity).
• SheetController item selection API:
  • selectItem(Object item) — select item + animate to half-expanded preview
  • clearSelection() — deferred selection clearing (null-out after collapse animation completes)
  • animateToSnap(SnapPoint) — named snap animation
  • animateToItemDetail(Object item) — select + animate directly to expanded detail
  • selectedItem / hasSelection getters
• SheetState.selectedItem and SheetState.hasSelection for list-driven mode context.
• SheetScaffold.contentLayerBuilder — custom content composition hook for list-driven mode.
• Magnetic snap attraction in DefaultSheetPhysics (opt-in via enableMagneticSnap).
• Platform-aware physics tuning (iOS/macOS softer rubber-band, Android stiffer).
• Configurable flickSensitivity multiplier on DefaultSheetPhysics.
• SheetPhysics.magneticForce() abstract method with default no-op implementation.
• Dual-mode example app with navigation hub for both page-driven and list-driven demos.
• Commerce-style list-driven example (product list, preview, detail, persistent cart bar).

Changed

• SheetScaffold barrier tap now calls clearSelection() when in list-driven mode (falls back to collapse() otherwise).
• SheetController._onAnimationStatus now handles deferred selection clearing via _pendingClearSelection flag.
• DefaultSheetPhysics uses flickSensitivity multiplier in snap resolution.

Migration from 0.1.x

No breaking changes. All existing MorphingSheet(...) usage works identically. New features are accessed via MorphingSheet.listDriven<T>(...) and the new SheetController selection API.

0.1.0 - 2026-03-03

Added

• Core MorphingSheet widget with multi-stage snap points (collapsed, half-expanded, fully expanded).
• SheetController (extends ChangeNotifier) for state-management-agnostic integration.
• Physics engine with abstract SheetPhysics and DefaultSheetPhysics implementation.
• Velocity-based snap resolution with configurable thresholds.
• Rubber-band resistance at sheet bounds.
• Continuous animation progress (0.0-1.0) driving all visual interpolations.
• Background scale + blur transform driven by sheet progress.
• Horizontal PageView switching (disabled at fully-expanded state).
• Custom curve presets (SheetCurves) optimized for sheet motion.
• TransitionSpec for per-element animation intervals.
• SheetConfig for full customization of snap points, curves, radii, elevation, and background effects.
• Sealed SheetVisualState hierarchy for type-safe state matching.
• Example app demonstrating all three sheet states with horizontal pages.