feat: Fix layout overflow and enhance responsive design for dashboard

[abcd1234davidchen]

This pull request enhances the HomePageScaffold in ap_common_flutter_ui with improved documentation, responsive layout logic, and code readability. The most significant changes include comprehensive DartDoc comments for public APIs, refactored and clarified layout methods for mobile and tablet devices, and improved logic for carousel and dashboard layouts.

Documentation Improvements

• Added detailed DartDoc comments to the HomePageScaffold class, its constructor, and all public fields and methods, making the widget's API much more understandable for future maintainers and users. [1] [2] [3] [4] [5] [6] [7] [8]

Responsive Layout Enhancements

• Refactored the carousel and dashboard layouts to provide distinct experiences for mobile portrait, mobile landscape, and tablet devices. This includes new logic for splitting the screen and choosing between vertical and horizontal arrangements based on orientation and device type. [1] [2] [3]
• Introduced _buildLandscapePhonePageView for optimized landscape layouts on mobile, using a side-by-side row for images and titles.

Layout and Sizing Logic

• Improved carousel and dashboard sizing calculations, allocating 60% of available height to the carousel (bounded between 240 and 600 pixels) and ensuring a visually balanced layout across device sizes.
• Adjusted viewportFraction logic in _homebody to better fit different device types and orientations, ensuring carousel cards are sized appropriately.

Code Quality and Maintainability

• Replaced magic numbers and unclear calculations with well-commented, maintainable logic for UI sizing and layout. [1] [2]
• Added documentation and refactored methods for showing dialogs and SnackBars, improving clarity and maintainability. [1] [2]

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation comments to the HomePageScaffold and introduces a new landscape layout for mobile devices. It also updates the dashboard layout and viewportFraction logic to better support tablet and mobile orientations. The review identified a significant issue regarding the lifecycle management of PageController within the _homebody method, which needs to be moved to initState and dispose to prevent memory leaks and state resets. Additionally, a suggestion was made to improve text handling in the landscape layout by adding maxLines and overflow properties to prevent UI overflow.

[gemini-code-assist]

The PageController is being instantiated inside the _homebody method, which is called during every build (e.g., on orientation change or when setState is called). This causes the scroll position to reset to 0 and adds a new listener on every rebuild, leading to memory leaks and a broken user experience when swiping. The PageController should be managed in the state's initState and dispose methods. To handle dynamic viewportFraction, you should recreate the controller only when the orientation changes, ensuring you preserve the current page and dispose of the previous controller.

[gemini-code-assist]

In the landscape phone layout, the announcement title is constrained to half the screen width. Long titles might overflow the available vertical space if they wrap too many times. Consider adding maxLines and overflow to the Text widget to ensure a consistent layout.

        Widget titleWidget = Text(
          announcement.title,
          textAlign: TextAlign.center,
          maxLines: 2,
          overflow: TextOverflow.ellipsis,
          style: TextStyle(
            fontSize: 20.0,
            color: Theme.of(context).colorScheme.onSurfaceVariant,
            fontWeight: FontWeight.w500,
          ),
        );