@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/patterns-standards/SUBMENU_HOVER_DROPDOWN_PATTERN.md

@@ -0,0 +1,225 @@
+# Submenu Hover Dropdown Pattern
+
+## Category
+patterns-standards / navigation
+
+## Problem
+
+Navigation menus with hierarchical items (parent/child) need hover-to-reveal dropdowns on desktop and accordion expand/collapse on mobile. A common bug is the dropdown disappearing when the mouse crosses the gap between the parent item and the dropdown panel. This happens because the `mouseleave` event fires on the parent before `mouseenter` fires on the dropdown, causing the submenu to close instantly.
+
+Additionally, menu items with `type: 'page'` require backend JOIN queries to resolve page slugs for correct URL generation.
+
+---
+
+## Solution - Desktop Hover with setTimeout Delay
+
+Use a `useRef` for a timeout ID and a `setTimeout` delay pattern. The 150ms delay gives users time to move their mouse from the parent nav item to the dropdown panel without it closing.
+
+```javascript
+const submenuTimeoutRef = useRef(null);
+const [openSubmenu, setOpenSubmenu] = useState(null);
+
+// On mouse enter parent item:
+const handleMouseEnter = (itemId) => {
+    if (submenuTimeoutRef.current) {
+        clearTimeout(submenuTimeoutRef.current);
+        submenuTimeoutRef.current = null;
+    }
+    setOpenSubmenu(itemId);
+};
+
+// On mouse leave (both parent item AND dropdown panel share this):
+const handleMouseLeave = () => {
+    submenuTimeoutRef.current = setTimeout(() => {
+        setOpenSubmenu(null);
+    }, 150); // 150ms delay prevents flicker
+};
+```
+
+### Why This Works
+
+Both the parent menu item and the dropdown panel use the **same** `onMouseEnter` and `onMouseLeave` handlers. When the mouse leaves the parent and enters the dropdown within 150ms, `handleMouseEnter` fires on the dropdown and clears the pending timeout before it can close the submenu.
+
+### JSX Structure (Desktop)
+
+```jsx
+{/* Parent wrapper - position: relative for absolute dropdown */}
+<div
+    className="relative"
+    onMouseEnter={() => handleMouseEnter(item.id)}
+    onMouseLeave={handleMouseLeave}
+>
+    {/* Parent nav item */}
+    <a href={getItemUrl(item)} className="flex items-center gap-1 px-3 py-2">
+        {item.label}
+        <ChevronDown className="h-4 w-4" />
+    </a>
+
+    {/* Dropdown panel - position: absolute, top: 100% */}
+    {openSubmenu === item.id && item.children?.length > 0 && (
+        <div
+            className="absolute left-0 top-full mt-1 w-48 bg-white shadow-lg rounded-md py-1 z-50"
+            onMouseEnter={() => handleMouseEnter(item.id)}
+            onMouseLeave={handleMouseLeave}
+        >
+            {item.children.map(child => (
+                <a key={child.id} href={getItemUrl(child)} className="block px-4 py-2 hover:bg-gray-100">
+                    {child.label}
+                </a>
+            ))}
+        </div>
+    )}
+</div>
+```
+
+### Cleanup on Unmount
+
+Always clear the timeout when the component unmounts to prevent state updates on unmounted components:
+
+```javascript
+useEffect(() => {
+    return () => {
+        if (submenuTimeoutRef.current) {
+            clearTimeout(submenuTimeoutRef.current);
+        }
+    };
+}, []);
+```
+
+---
+
+## Solution - Mobile Accordion
+
+On mobile, submenus should expand/collapse via tap using a `Set` to track which items are expanded:
+
+```javascript
+const [expandedMobileItems, setExpandedMobileItems] = useState(new Set());
+
+const toggleMobileSubmenu = (itemId) => {
+    setExpandedMobileItems(prev => {
+        const next = new Set(prev);
+        if (next.has(itemId)) next.delete(itemId);
+        else next.add(itemId);
+        return next;
+    });
+};
+```
+
+### JSX Structure (Mobile)
+
+```jsx
+<div className="space-y-1">
+    {item.children?.length > 0 ? (
+        <>
+            <button
+                onClick={() => toggleMobileSubmenu(item.id)}
+                className="w-full flex items-center justify-between px-4 py-2"
+            >
+                <span>{item.label}</span>
+                <ChevronDown className={`h-4 w-4 transition-transform ${
+                    expandedMobileItems.has(item.id) ? 'rotate-180' : ''
+                }`} />
+            </button>
+            {expandedMobileItems.has(item.id) && (
+                <div className="pl-6 space-y-1">
+                    {item.children.map(child => (
+                        <a key={child.id} href={getItemUrl(child)} className="block px-4 py-2">
+                            {child.label}
+                        </a>
+                    ))}
+                </div>
+            )}
+        </>
+    ) : (
+        <a href={getItemUrl(item)} className="block px-4 py-2">
+            {item.label}
+        </a>
+    )}
+</div>
+```
+
+---
+
+## Solution - Backend: Page-Type Menu Items
+
+Menu items with `type: 'page'` reference a page via `page_id`. The backend MUST JOIN with the `pages` table to include the page slug so the frontend can generate correct URLs:
+
+```sql
+SELECT mi.*, p.slug AS page_slug
+FROM menu_items mi
+LEFT JOIN pages p ON mi.page_id = p.id
+WHERE mi.menu_id = ${menu.id}
+ORDER BY mi.position ASC
+```
+
+### Frontend URL Resolution
+
+The `getItemUrl` helper must check `page_slug` first, then fall back to `page_id` and raw URL:
+
+```javascript
+const getItemUrl = (item) => {
+    if (item.type === 'page' && item.page_slug) {
+        return '/' + item.page_slug;
+    }
+    if (item.type === 'page' && item.page_id) {
+        return item.url || '#'; // fallback
+    }
+    if (item.url && !item.url.startsWith('http') && !item.url.startsWith('/')) {
+        return '/' + item.url;
+    }
+    return item.url || '#';
+};
+```
+
+---
+
+## Key Implementation Notes
+
+1. **Both parent and dropdown use the same `onMouseEnter`/`onMouseLeave` handlers** -- this is what makes the gap-crossing work.
+2. **Dropdown panel uses `position: absolute`** with `top: 100%` to appear below the parent.
+3. **Desktop dropdown wrapper**: `position: relative` on the parent container so the absolute dropdown positions correctly.
+4. **Theme compatibility**: For theme files in `/themes/`, use `useRef` and `useState` from React directly (no npm imports allowed -- see `CLAUDE.md` Theme Development CRITICAL RULES).
+5. **Cleanup**: Clear timeout on component unmount via `useEffect` return callback.
+6. **Mobile sidebar must have `lg:hidden`** on toggle button, panel, and backdrop (three elements).
+7. **150ms is the sweet spot** -- shorter causes flicker, longer feels sluggish.
+
+---
+
+## Files Modified (MERN LMS)
+
+| File | Role |
+|------|------|
+| `client/src/components/layout/Header.jsx` | Classic theme header |
+| `themes/aurora-borealis/components/layout/Header.jsx` | Aurora Borealis theme |
+| `themes/celestial/components/layout/Header.jsx` | Celestial theme |
+| `themes/melchizedek-order/components/layout/Header.jsx` | Melchizedek Order theme |
+| `themes/royal-priesthood/components/layout/Header.jsx` | Royal Priesthood theme |
+| `themes/prosperity/components/layout/Header.jsx` | Prosperity theme |
+| `themes/prophetic-academy/components/layout/Header.jsx` | Prophetic Academy theme |
+| `server/controllers/menuController.js` | Backend JOIN fix for page slugs |
+
+---
+
+## When to Use
+
+- Any navigation menu with parent/child hierarchy
+- Dropdown menus that appear on hover (desktop)
+- Mobile-responsive navigation with accordion submenus
+- Page-type menu items that need slug resolution from the database
+- Theme components that cannot import npm packages directly
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Forgetting to share handlers between parent and dropdown** -- the dropdown must also call `handleMouseEnter`/`handleMouseLeave` or it will close when the mouse enters it.
+2. **Using `onMouseOver`/`onMouseOut` instead of `onMouseEnter`/`onMouseLeave`** -- the former bubble from children and cause erratic behavior.
+3. **Not clearing the timeout on unmount** -- leads to "setState on unmounted component" warnings.
+4. **Missing the LEFT JOIN on pages** -- page-type menu items will have no slug and render as `#` links.
+5. **Importing `react-router-dom` Link in theme files** -- theme files are outside the Vite workspace; use plain `<a>` tags or a local Link wrapper.
+
+---
+
+## Tags
+
+navigation, submenu, hover, dropdown, accordion, mobile, menu, react, setTimeout, useRef, page-slug, backend-join, theme-compatibility

package/skills-library/patterns-standards/TAILWIND_TEXT_VISIBILITY_OVERRIDE.md

@@ -0,0 +1,322 @@
+# Tailwind CSS Text Visibility - Overriding Parent Text Colors
+
+## The Problem
+
+Button text was completely invisible on pricing cards because the parent button's `text-white` class was rendering white text on a light blue/green background.
+
+### Error Symptoms
+
+- "Upgrade" and "Downgrade" button text not visible
+- Text only appeared when highlighted (selection)
+- Same button worked on some cards but not others
+- Inline styles with `color: badgeColor` didn't override the issue
+
+### Why It Was Hard
+
+1. **CSS Specificity Confusion** - Inline styles should override classes, but Tailwind generates utilities with `!important`
+2. **Dynamic Styling** - Featured cards got different classes (`text-white`) vs non-featured cards (`text-gray-800`)
+3. **Inheritance Issues** - Button text inherited parent's text color, but inline style only applied to parent
+4. **Cache Masking** - Browser cache made it seem like deployments weren't working
+5. **Context-Dependent** - Problem only appeared when user had active membership (showing upgrade/downgrade)
+
+### Impact
+
+- Critical UX issue - users couldn't see upgrade buttons
+- Affected conversion funnel (memberships)
+- Required multiple deploys to fix
+- Wasted time debugging inline styles vs class specificity
+
+---
+
+## The Solution
+
+### Root Cause
+
+The button had conditional classes based on whether the card was "featured":
+
+```jsx
+className={`w-full py-3 px-6 rounded-lg font-semibold transition ${
+  isFeatured
+    ? 'bg-primary-600 text-white hover:bg-primary-700'  // ← text-white here
+    : 'bg-gray-100 text-gray-800 hover:bg-gray-200'
+}`}
+style={
+  !isFeatured
+    ? { backgroundColor: level.badge_color + '20', color: level.badge_color }
+    : {}
+}
+```
+
+**The Problem Flow:**
+1. Partners card is marked as `isFeatured = true` in database
+2. Button gets `text-white` class
+3. Button text (upgrade/downgrade) inherits `text-white`
+4. Background is light blue → invisible white text
+
+**Why Inline Styles Didn't Work:**
+- Inline `color` was on the `<button>` element
+- Text was in a `<span>` child element
+- CSS inheritance applied `text-white` to the span
+- Needed to override on the span itself, not parent
+
+### How to Fix
+
+**Add explicit text color class directly to the text element:**
+
+```jsx
+// ❌ BAD - text inherits parent's text-white
+<button className="text-white bg-blue-500">
+  <span className="flex items-center gap-2">
+    <ArrowUp />
+    Upgrade
+  </span>
+</button>
+
+// ✅ GOOD - explicit override on text element
+<button className="text-white bg-blue-500">
+  <span className="flex items-center gap-2 text-gray-900">
+    <ArrowUp />
+    Upgrade
+  </span>
+</button>
+```
+
+**Complete Fix:**
+
+```jsx
+{currentMembership && currentMembership.status === 'active' ? (
+  // Show upgrade/downgrade based on access_rank
+  (level.access_rank || 0) > (currentMembership.access_rank || 0) ? (
+    <span className="flex items-center justify-center gap-2 font-bold text-gray-900">
+      <ArrowUp className="w-4 h-4" />
+      Upgrade
+    </span>
+  ) : (
+    <span className="flex items-center justify-center gap-2 font-bold text-gray-900">
+      <ArrowDown className="w-4 h-4" />
+      Downgrade
+    </span>
+  )
+) : (
+  'Subscribe Now'
+)}
+```
+
+**Key Insight:**
+> Don't try to override parent text color with inline styles on parent.
+> Add explicit Tailwind class (`text-gray-900`) directly to the text element.
+
+---
+
+## Testing the Fix
+
+### Visual Test
+1. Navigate to `/pricing` page while logged in with active membership
+2. Look at cards where you can upgrade
+3. Button should show dark text ("Upgrade") clearly visible
+4. Works on both light and dark backgrounds
+
+### Browser Cache Warning
+⚠️ **Always hard refresh after deployment:**
+- `Ctrl + Shift + R` (Windows/Linux)
+- `Cmd + Shift + R` (Mac)
+- Or open DevTools → Network tab → Check "Disable cache"
+
+### Test Cases
+
+```jsx
+// Test 1: Featured card with upgrade button
+<PricingCard
+  isFeatured={true}
+  showUpgrade={true}
+/>
+// Expected: Dark text on light background (visible)
+
+// Test 2: Non-featured card with downgrade button
+<PricingCard
+  isFeatured={false}
+  showDowngrade={true}
+/>
+// Expected: Dark text on badge-colored background (visible)
+
+// Test 3: Current plan (no upgrade/downgrade)
+<PricingCard
+  isCurrentPlan={true}
+/>
+// Expected: "Current Plan" text (should match card style)
+```
+
+---
+
+## Prevention
+
+### 1. Always Consider Text Contrast
+```jsx
+// Check: What background will this text appear on?
+// If background can vary (light/dark), use explicit text color
+```
+
+### 2. Avoid Relying on Inheritance for Important Text
+```jsx
+// ❌ BAD - relies on inheritance
+<button className="text-white">
+  <span>{dynamicText}</span>
+</button>
+
+// ✅ GOOD - explicit control
+<button className="text-white">
+  <span className="text-gray-900">{dynamicText}</span>
+</button>
+```
+
+### 3. Test with Different Card States
+- Test featured vs non-featured
+- Test with/without active membership
+- Test different badge colors (light/dark)
+- Test on both localhost AND production (cache differences)
+
+### 4. Use Contrast Checking Tools
+- Browser DevTools → Accessibility tab
+- Check color contrast ratio (WCAG AA: 4.5:1 minimum)
+
+### 5. Document Dynamic Styling
+```jsx
+// Comment complex conditional styling
+// Featured cards: bg-primary-600 text-white
+// Non-featured: bg-gray-100 text-gray-800
+// Upgrade text: ALWAYS text-gray-900 (overrides parent)
+```
+
+---
+
+## Related Patterns
+
+- [Tailwind CSS Specificity Rules](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values)
+- [CSS Inheritance and Cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade)
+- [WCAG Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Using inline styles for text color** - They don't override Tailwind utilities on child elements
+- ❌ **Assuming inheritance works like props** - CSS inheritance is parent → child only
+- ❌ **Not testing with real data** - Featured status might come from database
+- ❌ **Forgetting browser cache** - Hard refresh after every deployment
+- ❌ **Overriding on wrong element** - Override on the text element, not parent
+- ❌ **Using `!important` as band-aid** - Fix the specificity issue properly
+
+---
+
+## CSS Specificity Refresher
+
+**Order of specificity (low to high):**
+1. Element selectors (`button`, `span`)
+2. Class selectors (`.text-white`)
+3. Inline styles (`style="color: white"`)
+4. `!important` flag
+
+**Tailwind utilities:**
+- Most Tailwind utilities are just classes
+- No `!important` by default (unless you add `!` prefix)
+- Child elements inherit text color unless explicitly overridden
+
+**Inheritance vs Specificity:**
+- Inheritance: Parent's `color` flows to children
+- Specificity: Explicit class on child beats inherited value
+- Solution: Add explicit class to child element
+
+---
+
+## Real-World Example
+
+**Scenario:** Pricing page with 3 tiers (Free, Partners, Premium)
+- Partners tier is featured (light blue background)
+- User is on Free tier, can upgrade to Partners
+- Button shows "Upgrade" but text is invisible
+
+**Before Fix:**
+```jsx
+<button className="bg-blue-100 text-white">
+  <span className="flex items-center gap-2">
+    <ArrowUp className="w-4 h-4" />
+    Upgrade  {/* ← invisible white text */}
+  </span>
+</button>
+```
+
+**After Fix:**
+```jsx
+<button className="bg-blue-100 text-white">
+  <span className="flex items-center gap-2 text-gray-900">
+    <ArrowUp className="w-4 h-4" />
+    Upgrade  {/* ← visible dark text */}
+  </span>
+</button>
+```
+
+**Contrast Ratios:**
+- Before: White on light blue = 1.5:1 (FAIL)
+- After: Dark gray on light blue = 8.2:1 (PASS)
+
+---
+
+## Resources
+
+- [Tailwind CSS Docs - Text Color](https://tailwindcss.com/docs/text-color)
+- [MDN - CSS Inheritance](https://developer.mozilla.org/en-US/docs/Web/CSS/inheritance)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Chrome DevTools - Accessibility](https://developer.chrome.com/docs/devtools/accessibility/reference/)
+
+---
+
+## Time to Implement
+
+**5-10 minutes** once you know the pattern (add explicit text color class)
+
+**Initial debugging time:** 30-60 minutes (finding root cause, testing inline styles, etc.)
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Easy fix once identified, but tricky to debug
+
+**Why difficult:**
+- CSS specificity can be confusing
+- Inheritance isn't obvious in JSX
+- Browser cache hides deployments
+- Conditional styling adds complexity
+
+---
+
+## Author Notes
+
+This bug burned 2 hours across 3 deployments because:
+1. First fix tried inline styles (didn't work - wrong element)
+2. Second fix removed inline color but didn't add explicit override
+3. Third fix added `text-gray-900` to the right element (worked!)
+
+**Key lesson:** When text is invisible, check BOTH:
+- What background it's on (contrast)
+- What parent text color it's inheriting
+
+The fix is almost always: **add explicit text color class to the text element itself.**
+
+Browser cache also made this harder - each deploy looked like it "didn't work" until hard refresh.
+
+**Pro tip:** When debugging text visibility in Tailwind:
+1. Use browser inspector to see actual computed color
+2. Check parent element classes
+3. Add explicit text color to child (don't rely on inheritance)
+4. Hard refresh to verify deployment
+
+---
+
+**Related Issues:**
+- Commit: `eff51d6` - Final fix
+- File: `client/src/pages/Pricing.jsx:534`
+- Date: 2026-02-15
+- Project: MERN Community LMS
+
+---
+
+**Future Agents:** If you see invisible text on buttons, check this skill first. It's almost always a parent `text-white` + light background issue. Add explicit dark text class to the child element.