LayrzLayout

LayrzLayout

SCOPE NOT YET DEFINED — This page is a placeholder capturing the team's intent and requirements discovery. Arguments and full specification are explicitly to be determined during Phase M5 planning.

---

Overview

LayrzLayout is a top-level application scaffold component that orchestrates navigation, user identity, and main content area presentation. Unlike ThemedLayout in layrz_theme (which supports multiple configurable presentations), LayrzLayout commits to a single, deliberate design system for layrz_ui.

Design Principles

• One design system: layrz_ui does not support multiple competing layout styles. A single, consistent presentation is chosen and locked.
• Desktop and mobile separation: Navigation and layout adapt to breakpoints, but the underlying design philosophy remains constant.
• Navigator item hierarchy: Support for both top-level pages and nested sub-pages via navigator items.
• User identity and actions: Display user profile, settings, logout, and theme switching in a consistent location.

---

What IS Known

Metadata

Phase: M5 (Layout layer)
Domain: Layout
Primitive: Hand-rolled (no Material Scaffold / Material AppBar outside Material constraints)
Reference: ThemedLayout (layrz_theme, scope very large)

Stated Intent

From team discussion: "kinda ThemedLayout, but FIXED TO ONE SINGLE DESIGN SYSTEM".

layrz_theme's ThemedLayout is highly flexible, supporting multiple presentation modes and customization. layrz_ui must resolve this flexibility into a single, intentional design. This is the core of the scope work.

---

What REQUIRES SCOPE DECISIONS

The following are the fundamental open questions. DO NOT answer these in implementation — answers must be decided and documented here first.

1. Desktop Layout Presentations

layrz_theme supports three desktop navigation styles:

• mini: Minimal sidebar (icons only, small width, maximizes content area).
• sidebar: Full-width sidebar (text labels, wider, more space for navigation).
• dual: Dual-bar layout (narrow toolbar + top app bar, most complex).

DECISION REQUIRED: Does layrz_ui keep all three, or commit to one? If multiple, can the user choose, or is it determined by breakpoint/context?

2. Mobile Layout Presentations

layrz_theme supports two mobile navigation styles:

• appBar: Traditional Material-style app bar at top, hamburger drawer navigation.
• bottomBar: Navigation bar at the bottom of the screen (newer paradigm).

DECISION REQUIRED: Does layrz_ui keep both, or commit to one mobile presentation? If both, how is the choice made (user preference, breakpoint, route)?

3. Navigator Item Types

layrz_theme defines several navigator item types that would need equivalents in layrz_ui:

• ThemedNavigatorPage: A page entry with icon, label, path, and optional breadcrumb. Supports nesting (children for sub-pages).
• ThemedNavigatorAction: An action/button-like item (does not navigate; invokes a callback).
• ThemedNavigatorWidget: A custom widget slot in the navigation area.
• ThemedNavigatorSeparator: A visual separator (divider or spacing).
• ThemedNavigatorLabel: A label/group heading.
• ThemedNotificationItem: A notification badge or indicator (for unread counts, etc.).

DECISION REQUIRED: Which of these types survive in layrz_ui, and do they carry the same API shape?

4. Content Area and Body Layout

• Does the body content have built-in padding and safe area handling?
• Is there a breadcrumb / page header automatically rendered based on the current route?
• Can this be disabled per-page?

DECISION REQUIRED: Padding defaults, breadcrumb integration, and per-page customization scope.

5. User Profile and Settings Area

layrz_theme's ThemedLayout displays user name, avatar, and buttons for settings / profile / logout / theme switch. The UI for these is tightly coupled to the navigation style (sidebar vs. mobile app bar).

DECISION REQUIRED: Does layrz_ui include this "user chrome"? If yes, is it always shown, or only on certain layouts / breakpoints?

6. Persistent vs. Transient Items

layrz_theme distinguishes between:

• items: Main navigation pages (shown in all layouts).
• persistentItems: Secondary actions (shown in some layouts, positioned differently on mobile vs. desktop).

DECISION REQUIRED: Does layrz_ui preserve this distinction, or unify into a single item list?

7. Notifications and Badges

layrz_theme includes notifications: List<ThemedNotificationItem> for displaying unread badges, alerts, etc., typically in the app bar or sidebar.

DECISION REQUIRED: Is notification support included? If yes, what visual presentation (badges, dots, counts)?

---

Reference: ThemedLayout API Shape

For comparison and discovery, ThemedLayout from layrz_theme has this constructor:

const ThemedLayout({
  ThemedLayoutStyle style = .mini,
  ThemedMobileLayoutStyle mobileStyle = .bottomBar,
  required Widget body,
  List<ThemedNavigatorItem> items = const [],
  String homePath = '/home',
  bool disableLeading = false,
  bool enableAbout = true,
  VoidCallback? onSettingsTap,
  VoidCallback? onProfileTap,
  VoidCallback? onLogoutTap,
  VoidCallback? onThemeSwitchTap,
  required String appTitle,
  String companyName = 'Golden M, Inc',
  required AppThemedAsset logo,
  required AppThemedAsset favicon,
  String userName = "Golden M",
  Avatar? userDynamicAvatar,
  String? version,
  List<ThemedNavigatorItem> additionalActions = const [],
  Color? backgroundColor,
  List<ThemedNavigatorItem> persistentItems = const [],
  List<ThemedNotificationItem> notifications = const [],
  double mobileBreakpoint = 1264,
  EdgeInsetsGeometry padding = const EdgeInsets.all(10),
  bool disableSafeArea = false,
  ThemedNavigatorPushFunction? onNavigatorPush,
  ThemdNavigatorPopFunction? onNavigatorPop,
  bool isBackEnabled = true,
  String? currentPath,
  bool enableNotifications = true,
  double avatarRadius = 5,
  bool enableBreadcumb = true,
  EdgeInsetsGeometry breadcumbPadding = const EdgeInsets.only(left: 10, top: 10, right: 10),
})

Note: This is large and includes many presentation modes and options. The layrz_ui version must make deliberate choices about which of these capabilities are actually needed.

---

Next Steps (for Phase M5 planning)

1. Design review: Confirm or adjust the desktop / mobile layout breakdown.
2. Navigator item scope: Finalize which item types are needed and their API.
3. User chrome specification: Decide on user profile / settings affordances.
4. Route integration: Clarify how routing and breadcrumbs are integrated.
5. Design reference: Attach Figma or wireframe showing the chosen layout(s) in light and dark themes.

---

Last updated: 2026-08-13
Related documents: Component Catalog, Architecture, Roadmap