Merge pull request #270 from moderntribe/feature/MOOSE-156/consolidade-navigation-block-styles

[MOOSE-156] Consolidade navigation block styles

Author: GeoffDusome

docs/navigation-blocks.md

@@ -8,13 +8,30 @@ The site navigation system is built using a collection of custom WordPress block
 
 ### Block Hierarchy
 
-The navigation system consists of four main blocks that work together:
+The navigation system consists of four main blocks that work together with a centralized styling approach:
 
-1. **Navigation Wrapper** (`tribe/navigation-wrapper`) - Structural container
+1. **Navigation Wrapper** (`tribe/navigation-wrapper`) - Central styling coordinator and structural container
 2. **Mega Menu Item** (`tribe/mega-menu-item`) - Complex dropdown menus
 3. **Standard Menu Item** (`tribe/standard-menu-item`) - Simple menu items with optional dropdowns
 4. **Navigation Link** (`tribe/navigation-link`) - Individual link items
 
+### CSS Architecture
+
+The styling architecture follows a centralized coordinator pattern:
+
+**Navigation Wrapper** acts as the central styling coordinator that handles:
+- Consolidated toggle button styles (shared between mega and standard menu items)
+- First-level navigation styling with animated underlines
+- Context-specific behavior for Primary vs Utility menus
+- Responsive adaptations and mobile behavior
+
+**Individual Blocks** handle only their specific content:
+- **Navigation Link**: Base link styling only
+- **Mega Menu Item**: Dropdown container and content styling
+- **Standard Menu Item**: Basic positioning and submenu wrapper styling
+
+This architecture eliminates code duplication and creates a single source of truth for navigation styling.
+
 
 ## HTML Structure & Implementation
 
@@ -102,16 +119,24 @@ The navigation system consists of four main blocks that work together:
 
 ### 1. Navigation Wrapper (`tribe/navigation-wrapper`)
 
-**Purpose**: A structural block that wraps menu items in a semantic `<nav>` tag with no added styles.
+**Purpose**: Central styling coordinator that provides semantic structure and handles all first-level navigation styling.
 
 **Location**: `wp-content/themes/core/blocks/tribe/navigation-wrapper/`
 
 **Features**:
 - Provides semantic HTML structure with `<nav>` element
 - Supports `aria-label` attribute for accessibility
-- No visual styling (purely structural)
-- Supports inner blocks and alignment
-- Acts as a container for menu items
+- **Consolidated toggle button styling** for both mega and standard menu items
+- **Unified first-level navigation styling** with animated underlines
+- **Context-aware styling** for Primary vs Utility menu placement
+- Responsive behavior and mobile adaptations
+- Acts as the styling foundation for all navigation components
+
+**Styling Responsibilities**:
+- Toggle button styles (chevrons, padding, hover states)
+- First-level navigation item styling (fonts, colors, underlines)
+- Context-specific overrides for different menu types
+- Mobile responsive adaptations
 
 **Attributes**:
 - `ariaLabel` (string) - Accessible label for the navigation
@@ -125,17 +150,22 @@ The navigation system consists of four main blocks that work together:
 
 ### 2. Mega Menu Item (`tribe/mega-menu-item`)
 
-**Purpose**: Enhanced dropdown menus with rich content capabilities for complex navigation structures.
+**Purpose**: Handles mega menu dropdown content and container functionality.
 
 **Location**: `wp-content/themes/core/blocks/tribe/mega-menu-item/`
 
 **Features**:
 - Configurable menu toggle label
 - Uses pattern template (`patterns/mega-dropdown`) for consistent content structure
 - Supports complex layouts and rich content within dropdowns
+- **Container queries** for responsive dropdown layouts
 - JavaScript interactions for opening/closing mega menus
 - Event-driven architecture with custom events
-- Full width layouts and grid alignment support
+
+**Styling Scope**:
+- **Dropdown content styling only** (first-level button styling handled by Navigation Wrapper)
+- Container queries for responsive layouts
+- Mega menu wrapper positioning and background
 
 **Attributes**:
 - `menuToggleLabel` (string) - Text label for the top-level navigation button
@@ -152,17 +182,22 @@ The navigation system consists of four main blocks that work together:
 
 ### 3. Standard Menu Item (`tribe/standard-menu-item`)
 
-**Purpose**: Simple menu items with optional dropdown functionality for basic navigation needs.
+**Purpose**: Handles basic menu item positioning and submenu wrapper functionality.
 
 **Location**: `wp-content/themes/core/blocks/tribe/standard-menu-item/`
 
 **Features**:
 - Toggle for enabling simple dropdown submenus
 - Only allows `tribe/navigation-link` as child blocks
 - Configurable menu toggle label when used as dropdown
-- Lightweight alternative to mega menu items
+- **Lightweight positioning and layout** (first-level styling handled by Navigation Wrapper)
 - Perfect for simple link lists
 
+**Styling Scope**:
+- **Basic positioning and layout only** (first-level button styling handled by Navigation Wrapper)
+- Toggle label styling (underline on hover)
+- Submenu wrapper positioning and behavior
+
 **Attributes**:
 - `hasSubMenu` (boolean) - Enables dropdown functionality
 - `menuToggleLabel` (string) - Text label when used as dropdown toggle
@@ -176,16 +211,20 @@ The navigation system consists of four main blocks that work together:
 
 ### 4. Navigation Link (`tribe/navigation-link`)
 
-**Purpose**: Individual link items within menu structures.
+**Purpose**: Provides base link styling with consistent behavior across all navigation contexts.
 
 **Location**: `wp-content/themes/core/blocks/tribe/navigation-link/`
 
 **Features**:
 - Rich text editing for link text
 - URL configuration with WordPress LinkControl component
 - Target/new window option
-- Can only be used as child of `tribe/standard-menu-item`
-- Proper link management with unlink functionality
+- **Base link styling only** (context-specific enhancements handled by Navigation Wrapper)
+- Consistent foundation across all menu types
+
+**Styling Scope**:
+- **Base link styles only**: underline, transitions, focus states
+- Context-specific styling (Primary vs Utility menu) handled by Navigation Wrapper
 
 **Attributes**:
 - `text` (string) - Link text content
@@ -200,6 +239,46 @@ The navigation system consists of four main blocks that work together:
 - Link control popover for URL management
 - Toolbar controls for link/unlink actions
 
+## Styling Architecture
+
+### Centralized Coordinator Pattern
+
+The navigation system uses a **centralized coordinator pattern** where the Navigation Wrapper acts as the central styling authority:
+
+```
+Navigation Wrapper (Coordinator)
+├── Toggle Button Styles (shared by mega & standard menu items)
+├── First-Level Navigation Styling (animated underlines, hover states)
+├── Context-Specific Overrides (Primary vs Utility menu)
+└── Responsive Adaptations (mobile behavior)
+
+Individual Blocks (Content-Specific)
+├── Navigation Link: Base link styles only
+├── Mega Menu Item: Dropdown container & content
+└── Standard Menu Item: Basic positioning & submenu wrapper
+```
+
+### Key Benefits
+
+**Eliminates Code Duplication**: Shared styles are defined once in Navigation Wrapper
+**Single Source of Truth**: Navigation behavior modifications happen in one place
+**Clear Separation**: Each block has a specific, well-defined styling responsibility
+**Easy Maintenance**: Changes to navigation styling require updates to only one file
+**Consistent Experience**: Unified first-level navigation behavior across all menu types
+
+### CSS File Organization
+
+**Navigation Wrapper** (`navigation-wrapper/style.pcss`):
+- Toggle button styles (consolidated)
+- Primary navigation first-level styles
+- Utility menu style overrides
+- Responsive behavior
+
+**Individual Block Files**:
+- **Navigation Link**: Base link foundation only
+- **Mega Menu Item**: Dropdown content and container queries
+- **Standard Menu Item**: Simple positioning and submenu wrapper
+
 ## JavaScript Architecture
 
 ### Event System
@@ -259,6 +338,30 @@ The navigation system integrates with:
 - Focus management for dropdown interactions
 - Screen reader friendly markup
 
+## Development Guidelines
+
+### Working with the Centralized Architecture
+
+#### **Making Navigation Styling Changes**
+
+**For First-Level Navigation Changes**: Edit `navigation-wrapper/style.pcss`
+- Toggle button styling (padding, colors, hover states)
+- Animated underlines and transitions
+- Font sizes and spacing
+- Context-specific behavior (Primary vs Utility)
+
+**For Individual Block Content**: Edit respective block files
+- `navigation-link/style.pcss`: Base link foundation only
+- `mega-menu-item/style.pcss`: Dropdown content and container queries
+- `standard-menu-item/style.pcss`: Basic positioning and submenu wrapper
+
+### Customization Points
+
+- **Navigation Wrapper**: Central coordinator for all first-level styling
+- **Patterns**: Modify `patterns/mega-dropdown` for mega menu layouts
+- **Individual Blocks**: Content-specific styling only
+- **Context Selectors**: Use `.site-header__navigation` and `.site-header__utility-menu` for targeting
+
 ## File Structure
 
 ```

wp-content/themes/core/blocks/tribe/mega-menu-item/style.pcss

@@ -1,9 +1,11 @@
 /* -------------------------------------------------------------------------
  *
- * Block - Mega Navigation Menu - Styles - FE / Editor
+ * Block - Tribe Mega Menu Item
+ *
+ * Handles styling for mega menu dropdown content and wrapper.
+ * First-level navigation button styles are consolidated in Navigation Wrapper.
  *
  * ------------------------------------------------------------------------- */
-
 .wp-block-tribe-mega-menu-item {
 	color: var(--color-text);
 
@@ -32,92 +34,6 @@
 	}
 }
 
-/* mega menu item button toggle */
-.tribe-mega-menu-item__toggle {
-	background-color: transparent;
-	border: 0;
-	padding: var(--spacer-10) var(--spacer-30) var(--spacer-20) var(--spacer-10);
-	position: relative;
-	color: var(--color-text);
-	transition: var(--transition);
-
-	@media (--mq-navigation-max) {
-		width: 100%;
-		font-size: var(--font-size-40);
-		text-align: left;
-		padding-left: 0;
-	}
-
-	&::before {
-		content: "";
-		width: 0;
-		height: 4px;
-		background-color: var(--masthead-navigation-accent-color);
-		position: absolute;
-		bottom: -4px;
-		left: var(--spacer-10);
-		transition: width 0.15s ease-in-out;
-		z-index: 11;
-
-		@media (--mq-navigation-max) {
-			display: none;
-		}
-	}
-
-	&::after {
-		content: "";
-		background-color: currentcolor;
-		display: block;
-		height: 16px;
-		width: 10px;
-		mask: var(--icon-chevron-right) center no-repeat;
-		mask-size: contain;
-		position: absolute;
-		right: 2px;
-		top: calc(var(--spacer-10) + 5px);
-		transform: rotate(90deg);
-		transition: var(--transition);
-	}
-
-	&:hover,
-	&:active,
-	.menu-item-active & {
-		outline: none;
-		color: var(--masthead-navigation-accent-color);
-
-		&::before {
-			width: calc(100% - var(--spacer-10));
-		}
-
-		@media (--mq-navigation-max) {
-			outline: revert;
-			color: var(--color-text);
-		}
-	}
-
-	&:focus-visible {
-		outline: 2px solid var(--masthead-navigation-accent-color);
-	}
-
-	/*  Hide border on closed menu items, even when hovered or active */
-	:not(.menu-item-active) & {
-
-		@media (--mq-navigation-max) {
-
-			&::before {
-				width: 0;
-			}
-		}
-	}
-
-	.menu-item-active & {
-
-		&::after {
-			transform: rotate(-90deg);
-		}
-	}
-}
-
 /* enhanced menu pattern wrapper */
 .site-header__mega-menu-item-wrapper {
 	width: 100%;

wp-content/themes/core/blocks/tribe/navigation-link/style.pcss

@@ -1,25 +1,29 @@
 /* -------------------------------------------------------------------------
  *
- * Block - Tribe Navigation Link - Styles - FE / Editor
+ * Block - Tribe Navigation Link
+ *
+ * Handles individual link styling with base behavior:
+ * - Base link styles (underline, transitions, focus states)
+ * - Consistent styling across all navigation contexts
+ *
+ * Context-specific enhancements are handled in Navigation Wrapper.
  *
  * ------------------------------------------------------------------------- */
 
 .wp-block-tribe-navigation-link {
+	text-decoration: underline 1px;
 	text-decoration-color: transparent;
 	transition: var(--transition);
 	color: var(--color-text);
 	display: block;
 
 	&:hover,
+	&:active,
 	&:focus {
 		text-decoration-color: currentcolor;
 	}
 
 	&:focus-visible {
 		outline: 2px solid var(--masthead-navigation-accent-color);
 	}
-
-	.site-header__utility-menu & {
-		font-size: 14px;
-	}
 }