by_ui 0.1.8

A modern, highly customizable Flutter UI component library featuring dynamic border buttons, scroll-driven animations, motion cards, toasts, and shrink-wrap dialogs

Changelog

All notable changes to the by_ui package will be documented in this file.

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

0.1.8

Added

• ByTabBar:
  • Fluid segmented tab bar and scrollable tabs rail component family.
  • Liquid Elastic Morphing: Stretches the sliding indicator pill dynamically between distant tabs (enableLiquidMorphing, liquidStretchFactor).
  • Dual Indicator Styles: Sliding pill capsule (ByTabIndicatorStyle.pill) and docked bottom underline bar (ByTabIndicatorStyle.underline).
  • Dynamic Perimeter Border Pulses: Running 3-phase laser beam on the active indicator (enableDynamicBorder, enableSelectionPulse, dynamicBorderColors) and outer container (enableOuterDynamicBorder, outerDynamicBorder).
  • Scrollable Tabs Rail: Horizontal scrolling (isScrollable: true) with concentric innerClipRadius anti-aliased viewport clipping and scroll notification isolation.
  • Rich Customization: Gradients (indicatorGradient), border width, container radius, indicator radius, text & icon color transitions, and badges (badge, badgeColor, badgeTextColor).
• ByBottomNav:
  • Dynamic glassmorphic floating navigation dock system.
  • Spring-Physics Interaction: Smooth spring item expansion and active indicator pill gliding.
  • Selection Border Pulse: 3-phase dynamic perimeter border beam pulse on item tap (enableSelectionPulse, selectionPulseColors).
  • Frosted Glassmorphism: Translucent background surface (enableFrostedGlass, blurSigma, surfaceOpacity).
  • Adaptive Layout: Fluid label/icon layout transitions with mobile-first badge counters (badge, badgeColor).
• BySidebar:
  • Responsive vertical navigation sidebar component family.
  • Dual Presentation Modes: Wide-screen docked sidebar ($\ge 700\text{px}$) and small-screen floating overlay drawer ($< 700\text{px}$) with dismissible scrim backdrop.
  • Tactile Toggle Placement: Header toggle button (togglePlacement: BySidebarTogglePlacement.header) or tactile bottom action tile (bottomAction).
  • Hover Auto-Expand Preview: Interactive hover-expand preview (enableHoverExpand) on desktop and web.
  • Rich Item Decorators: Section headers (BySidebarItem.section), trailing status widgets (trailing), collapsed tooltips, and badges.
• ByAutoShimmer:
  • Automated MVP-compliant skeleton layout generator.
  • Recursive Widget Inspection: Automatically produces high-fidelity bone placeholders (ByBone) matching exact card, text, avatar, and button dimensions.
  • Directional Wave Sweeps: Multi-tone gradient sweeps (direction: ByShimmerDirection.ltr, rtl, ttb, btt, diagonal).
  • Gradient Wave Customization: Rich gradient sweeps with shimmerGradient and customizable wave width (shimmerWaveWidth).
  • Seamless State Transitions: Zero-overflow cross-fade morphing between skeleton and loaded content (ClipRect + OverflowBox).
  • Standalone Bone Primitives: ByBone.square, ByBone.rounded, ByBone.circle, and ByBone.text.

Changed

• ByButton:
  • Standardized default dynamic beam colors (beamColorA, beamColorB) to pure white (Colors.white) across both light mode and dark mode for consistent high-contrast vibrancy.

Fixed

• ByAppBar & ByScrollScope:
  • Isolated ByScrollScope to ignore non-vertical scroll notifications (metrics.axis != Axis.vertical), preventing horizontal tab bar drags from triggering floating app bar states.
• ByTabBar:
  • Fixed rightmost tab clipping by factoring outer border stroke width into available inner width calculation.
  • Wrapped scrollable tabs rail in concentric innerClipRadius with anti-aliasing to eliminate straight vertical hard-edge indicator cutoff.

0.1.7

Fixed

• Enforced curly_braces_in_flow_control_structures linter rule across all core library components for 100% Pana static analysis score.
• Optimized BySequence preview GIF file size for fast loading on pub.dev.
• Added analysis_options.yaml to core package root with official flutter_lints.
• Removed unnecessary library directives to satisfy unnecessary_library_name lint.

0.1.6

Added

• ByButton:
  • Flagship, interactive button component family combining tactile ergonomics, fluid spatial animations, autonomous async state handling, and dynamic perimeter border pulses.
  • Visual Variants:
    • ByButtonVariant.filled: High-contrast filled action button.
    • ByButtonVariant.gradient: Vibrant multi-color gradient surface.
    • ByButtonVariant.outline: Clean bordered button with transparent backdrop.
    • ByButtonVariant.ghost: Minimal text button with subtle hover elevation.
  • Comprehensive State Management:
    • Interactive states: idle, hover, pressed, loading, and disabled.
    • Autonomous asynchronous execution: passing a Future<void> Function() to onPressed automatically triggers the loading state until completion.
    • Dedicated transactional state support (ByButtonState.idle, ByButtonState.loading, ByButtonState.success, ByButtonState.error).
    • Preserved button geometry during loading state to prevent layout reflows and content shifts.
    • 3-phase circular pulse spinner with customizable loading indicator widget (loadingWidget).
  • Dynamic Perimeter Border Pulses (ByDynamicBorderLayer):
    • Perimeter beam sweep animation following rounded rectangle geometry (RRect), including corner arcs.
    • Customizable beam color, gradient, length (beamLength), duration (pulseDuration), and easing curve.
    • Periodic background pulses (periodicPulseInterval) for persistent ambient call-to-actions.
    • State transition border pulses: automatically sweeps an energetic contrast pulse when transitioning from disabled to enabled state (enableTransitionPulseColors).
    • Manual trigger controls via ByDynamicBorderController.pulse().
  • Independent Border Widths:
    • Fine-grained control over resting border width (borderWidth) and active loading border width (loadingBorderWidth).
  • Theming & Ergonomics:
    • Five predefined size presets: ByButtonSize.xs, ByButtonSize.sm, ByButtonSize.md, ByButtonSize.lg, and ByButtonSize.xl.
    • Prefix leading widget, suffix trailing widget, spacing, floating corner badges (badge, badgeAlignment).
    • Unified styling via ByButtonStyle and tokens in ByButtonDefaults.
• ByDynamicBorder:
  • Standalone dynamic perimeter border layer system (ByDynamicBorder, ByDynamicBorderLayer, ByDynamicBorderController).
  • Geometric perimeter interpolation calculating straight edge runs and corner arc sweeps.
• ByDialog Dogfooding:
  • Integrated ByButton as the primary button engine in ByDialog.confirm and ByDialog.alert for cohesive design and tactile interaction.
• Documentation & Media:
  • Added animated preview GIF for BySequence (by_sequence.gif).
  • Added animated preview GIF for ByButton dynamic border pulse (by_button.gif).
  • Added official library logo banner (logo_by_ui.jpg).

Fixed

• Prevented framework setState() or markNeedsBuild() called during build assertion when triggering dynamic border animation controllers during widget build phases.
• Synchronized disabled-to-enabled transition pulse default colors to match surface contrast palettes.

0.1.5

Added

• BySequence:
  • New sequential, scroll-driven widget reveal and animation component family.
  • Zero-Boilerplate Scroll Animations: Progressively reveals children as the viewport scrolls without requiring manual ScrollController, AnimationController, or coordinate math.
  • GSAP-Inspired Motion System:
    • 1:1 Continuous Scrubbing: Direct bidirectional sync between scroll offset and animation progress (scrub: true).
    • Dynamic Batch Pacing (ScrollTrigger.batch): Automatic item grouping (groupSize) with configurable cascading stagger delays (groupStaggerDelay, groupStagger).
    • Viewport Trigger Line: Relative trigger threshold positioning from top to bottom (trigger: 0.0 to 1.0).
    • Initial Viewport Gating: Support for initialVisibleFraction and initialVisibleCount so initial items render crisp and ready while subsequent items animate on scroll.
    • Reverse & Replay Controls: Bidirectional reverse unwinding on scroll-up (reverse: true) and entry replay triggers (replay: true).
  • Granular Composition & Customization:
    • BySequenceAnimation: Configurable transformation presets and custom ranges for opacity, translateX, translateY, scale, and rotation.
    • BySequenceItem: Per-item animation, duration, curve, and trigger overrides.
    • BySequenceController: Headless controller for fine-grained progress observation and callback hooks (onProgress, onItemProgress, onItemEnter, onSequenceComplete).
    • BySequenceRange: Mathematical range interpolation utility with smooth lerpDouble.
  • Multi-Orientation Layout: Full support for both vertical (Axis.vertical) and horizontal (Axis.horizontal) sequences.

0.1.4

Added

• ByAppBar:
  • New dynamic floating and glassmorphic app bar component family.
  • Scroll-Driven Floating Transition: Smoothly animates between static edge-docked state and floating detached pill based on scroll distance threshold via ancestor ByScrollScope or custom ScrollController.
  • Frosted Glassmorphism: Integrated Gaussian blur filter (floatingBlurSigma) and configurable surface opacity (floatingOpacity).
  • Dynamic Sensor & Motion Tilt:
    • Directional gradient border stroke matching physical gyroscope/accelerometer tilt on mobile (Android / iOS).
    • Mouse cursor hover parallax tracking on desktop and web with automatic smooth return to resting pose.
    • Spatial directional glow and dynamic shadow projection (shadowGradient, shadowBlur, maxShadowOffset).
    • Ultra-Smooth Hermite Cubic Interpolation: Smoothstep blending between resting alignment and physical tilt vector, eliminating abrupt jumps and stutter when rotating or tilting mobile devices.
    • High-Refresh Physics Engine: Game interval hardware sampling (~50-60 Hz) and per-frame Ticker interpolation in ByTiltController.
    • Inner Shadow & Ambient Glow Control: Added enableInnerShadow (defaults to false) and innerShadowOpacity multiplier (with enableInnerGlow and innerGlowOpacity synonyms for ByCard API symmetry).
    • Even Neutral Resting Glow: Even, balanced edge-to-edge linear gradient ambient sheen in neutral resting pose (magnitude < 0.08), eliminating circular hot-spots.
  • Notch & Status Bar Handling:
    • Seamlessly covers the status bar/notch area with a solid background when static at the top (!isFloating).
    • Smoothly transitions notch coverage to transparent when floating so background content scrolls elegantly behind the floating pill.
  • Zero-Border Default & Complete Customization:
    • Border defaults to 0.0 (clean edge by default).
    • Full control over borders, linear gradients, margins, corner radii, elevation, toolbar height, and custom bottom widgets (e.g. TabBar).
    • Convenient static helper getContentTopPadding(context) for clean extendBodyBehindAppBar integration on Scaffold.
• ByCard:
  • Added dynamic inner sheen / luminous glow support (enableInnerGlow, innerGlowOpacity, innerGlowBlur) in ByCard and ByCardPainter reacting to directional lighting.
  • Refined neutral pose inner glow to use balanced linear gradient across the card when resting flat.
• ByToast:
  • Added typography font size customization with textSize and titleSize across ByToast, ByToastModel, ByToastCard, and all preset methods (showSuccess, showError, showWarning, showInfo).
• Documentation & Media:
  • Added animated preview GIF for ByAppBar dynamic floating motion and gradient border parallax (ByAppBar.gif).
  • Added interactive inner shadow toggle and opacity slider controls to AppBarShowcaseScreen.

0.1.3

Added

• ByCard:
  • New versatile card widget family featuring sleek styling, configurable padding, borders, corner radii, and drop shadows.
  • Card Variants & Constructors:
    • ByCard: Standard card with solid or custom background styling, customizable border width, and border color.
    • ByCard.gradient: Shorthand constructor for cards with vibrant linear gradient borders (colors, borderGradient, borderWidth).
    • ByCard.dynamicSensor: Zero-boilerplate dynamic motion card with responsive border gradient tracking:
      • Mobile (Android / iOS): Automatically responds to hardware device motion using gyroscope/accelerometer tilt with smooth low-pass filtering.
      • Desktop & Web: Seamlessly adapts to mouse cursor hover tracking with fluid spring glide back to neutral center position when the pointer exits.
  • Lifecycle-Safe Tilt Management: Built-in ByTiltController handles hardware stream subscriptions and listeners lazily on mount and disposes automatically on unmount without user boilerplate.
  • Configurable Motion Settings: Custom sensorSensitivity, maxSensorTilt, hoverSensitivity, and neutralAlignment.
  • Theming & Design Tokens: ByCardThemeData and ByCardDefaults for unified application-wide card styling.
• BySelectOption:
  • Reusable model and UI component for selectable options with active indicator, title, subtitle, icon, and badge support.
• Documentation & Media:
  • Added animated preview GIF for ByCard dynamic motion border gradient.

0.1.2

Added

• ByDialog:
  • Comprehensive button customization in ByDialog.confirm:
    • buttonBorderRadius: Customizable button corner radius.
    • reverseButtonOrder: Option to reverse button positions (Confirm left, Cancel right).
    • cancelColor: Option to convert cancel button into a solid filled button.
    • cancelBorderColor and cancelTextColor: Fine-grained negative button color tuning.
    • confirmTextColor: Customizable positive button text color.
    • onConfirm and onCancel: Direct lifecycle callbacks before modal dismiss.
  • Added buttonTextColor and buttonBorderRadius customization in ByDialog.alert and all presets (success, error, warning, info).
• Documentation & Media:
  • Added visual animated GIF previews for stacked cards, drag-to-dialog, and standalone modal dialogs.

0.1.1

Added

• ByToast:
  • Multi-anchor desktop & web corner positioning (topLeft, topRight, bottomLeft, bottomRight) alongside full-width top and bottom, with intelligent auto slide directions and per-anchor stack offsets.
  • Configurable background surface opacity (backgroundOpacity) for solid and gradient surfaces while keeping foreground text and icons at 100% clarity.
  • Configurable text truncation controls (maxLines defaults to 3, overflow defaults to TextOverflow.ellipsis).
  • Configurable title truncation options (titleMaxLines and titleOverflow).
  • Intelligent tap-to-expand fallback allowing standard toasts with long text to seamlessly morph into dialog view.
• ByToastMorphDialog:
  • Integrated dedicated ScrollController with custom scrollbar styling for long notification details.
  • Layout enhancements with edge-to-edge content scrolling and polished dividers.
• ByDialog:
  • Added text truncation controls (messageMaxLines, messageOverflow, titleMaxLines, titleOverflow) across alert, confirm, and presets (success, error, warning, info).

Fixed

• Fixed toast tap gesture detection when expanding messages into dialogs without custom onTap handlers.
• Fixed scroll controller disposal and viewport constraints in ByToastMorphDialog.

0.1.0

Added

• Initial public release of by_ui.
• ByToast: Modern notification and toast system.
  • Screen anchor positions: top and bottom.
  • Multi-directional entrance slide animations (fromTop, fromBottom, fromLeft, fromRight).
  • Animation styles: slideAndFade, bounce, scaleAndFade, slideOnly, fadeOnly.
  • Customizable prefixes (leading icons/widgets), suffixes (trailing actions/widgets), and close buttons.
  • Solid color and linear gradient background surfaces.
  • Swipe-to-dismiss gesture handling with smooth spring physics.
  • Presets: ByToast.showSuccess, ByToast.showError, ByToast.showWarning, ByToast.showInfo.
• ByToast Morphing Dialog:
  • Dual-interaction morphing: tap message text or drag toast towards screen center.
  • Seamless spatial translation from the toast's dragged position to center.
  • Pure wrap-content natural layout (shrink-wrap) with AnimatedSize and auto-scrolling constraints.
  • Two detail modes: Default text breakdown (Option 1) and custom widget builder (Option 2).
• ByDialog: Independent modern modal dialog component.
  • Presets: ByDialog.alert and ByDialog.confirm.
  • Full theme customization: gradients, corner radiuses, outline borders, custom barrier dismissibility, and animation easing.